From 7e9fb922d32451c3775c2024393ee8419a573623 Mon Sep 17 00:00:00 2001 From: DenisBrunet Date: Wed, 22 Jan 2025 11:33:08 +0100 Subject: [PATCH] Reference Guide pages: - Updated css style to have all pages in a max width central column. - Whole html pages has been nicely reformatted, though content has not been modified (except for 1 image size). --- docs/ReferenceGuide/about-rois.html | 249 +- docs/ReferenceGuide/all-processings.html | 473 +- docs/ReferenceGuide/cartool-options.html | 206 +- docs/ReferenceGuide/cartool.css | 20 + .../command-line-interface.html | 766 +- docs/ReferenceGuide/computing-erps.html | 5565 ++++++----- .../computing-inverse-solution-matrices.html | 8117 ++++++++++------- docs/ReferenceGuide/computing-ris.html | 1684 ++-- docs/ReferenceGuide/computing-statistics.html | 3343 ++++--- .../coregistering-electrodes-to-mri.html | 1302 +-- docs/ReferenceGuide/creating-rois.html | 2576 +++--- .../creating-template-electrodes.html | 672 +- docs/ReferenceGuide/eeg-display.html | 6791 ++++++++------ docs/ReferenceGuide/esi-display.html | 2467 +++-- docs/ReferenceGuide/file-calculator.html | 2507 ++--- .../ReferenceGuide/files-formats-cartool.html | 1875 ++-- docs/ReferenceGuide/files-formats-others.html | 2030 +++-- docs/ReferenceGuide/frequency-analysis.html | 2427 ++--- docs/ReferenceGuide/frequency-display.html | 1786 ++-- docs/ReferenceGuide/general-concepts.html | 1339 +-- docs/ReferenceGuide/index.html | 262 +- .../microstates-back-fitting-templates.html | 3902 ++++---- .../microstates-segmentation-display.html | 775 +- .../microstates-segmentation.html | 4507 +++++---- docs/ReferenceGuide/mri-display.html | 2349 +++-- docs/ReferenceGuide/mris-preprocessing.html | 1792 ++-- .../potentials-maps-display.html | 940 +- docs/ReferenceGuide/problems-resolution.html | 374 +- docs/ReferenceGuide/reprocess-tracks.html | 2236 +++-- docs/ReferenceGuide/ris-to-volumes.html | 1198 ++- .../terms-definitions-formulas.html | 1121 ++- docs/ReferenceGuide/tracks-interpolation.html | 2221 +++-- .../windows-general-commands.html | 1273 +-- 33 files changed, 39859 insertions(+), 29286 deletions(-) diff --git a/docs/ReferenceGuide/about-rois.html b/docs/ReferenceGuide/about-rois.html index 375f4991..13e2f388 100644 --- a/docs/ReferenceGuide/about-rois.html +++ b/docs/ReferenceGuide/about-rois.html @@ -2,103 +2,156 @@ Using ROIs - -

- Using ROIs

-

-  

-

- This page contains a short description of what can be done with the - ROIs in Cartool. Use the links below to access the details for each topic.

-

- Go here if you want to learn how to - create the .rois files - needed for these processings.

-

-  

-

- ROIs and Statistics

-

- The primary use of ROIs is for statistical - testing. The ROIs are computed on-the-fly, reducing data - dimensionality and increasing the signal to noise ratio (plus, it's cool).

-

- Averagings ROIs

-

- You can simply re-process your data - and reduce their dimensionalities / increase their signal to noise ratios.

-

- Using ROIs for display

-

- Or you can enhance the visualization of your data:

- -

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-   + + +

+ +

+ Using ROIs +

+

+   +

+

+ This page contains a short description of what can be done with the + ROIs in Cartool. Use the links below to access the details for each topic. +

+

+ Go here if you want to learn how to + create the .rois files + needed for these processings. +

+

+   +

+

+ ROIs and Statistics +

+

+ The primary use of ROIs is for + + statistical + testing + + . The ROIs are computed on-the-fly, reducing data + dimensionality and increasing the signal to noise ratio (plus, it's cool). +

+

+ Averagings ROIs +

+

+ You can simply re-process your data + and reduce their dimensionalities / increase their signal to noise ratios. +

+

+ Using ROIs for display +

+

+ Or you can enhance the visualization of your data: +

+ +

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

\ No newline at end of file diff --git a/docs/ReferenceGuide/all-processings.html b/docs/ReferenceGuide/all-processings.html index f4852729..e87b7e7a 100644 --- a/docs/ReferenceGuide/all-processings.html +++ b/docs/ReferenceGuide/all-processings.html @@ -2,214 +2,275 @@ Processing - -

- Processing

-

-  

-

- The menu Tools is - your central access to the most important processing of Cartool, - while you can find a few utilities under the File menu.

-

-  

-
- Tools menu
- File menu -
-

- Tools menu

+ +
+

+ Processing +

+

+   +

+

+ The menu Tools is + your central access to the most important processing of Cartool, + while you can find a few utilities under the File menu. +

+

+   +

+
+ Tools menu
+ File menu +
+

+ Tools menu +

-
EEG and Tracks
-
- Exporting / Reprocessing Tracks
- File Calculator
- Averaging EEG Files / Interactive
Averaging EEG Files / Batch
- Interpolating EEG Files
- Segmentation of EEG Files
- Fitting templates to EEG Files
Correlation / Coherence between files
Computing Templates / Centroids from cluster files
- Creating ROIs from Tracks
- Statistics on Tracks
Standardizing Tracks
Histogram of current EEG Tracks
Histogram of current EEG Time Frames
PCA on current EEG file
-
-
Frequency
-
-Frequency Analysis of EEG Files
-Averaging FREQ Files / Batch
-Correlation / Coherence between files
-Statistics on FREQ files
-
-
MRIs and Volumes
-
- MRIs Preprocessing
-Coregistering another MRI to current MRI
-Skull Stripping Full Head MRIs
-Brainstem Removal
-Bias Field Correction
-Extracting Grey Mask
-Extracting Black / Grey / White Matters
-
Electrodes Coordinates and Solution Points
-
- Coregistering Electrodes to Head MRI
-Creating ROIs for Electrodes / Solution Points
-Create a Template of Electrodes Coordinates
-Transforming XYZ or SPI Set of Points
-
-
Inverse Solution
-
-Creating Inverse Solution Matrices
-Computing Results of Inverse Solutions
- Results of Inverse Solutions to Volumes
- Statistics on - RIS files
Standardizing existing RIS files
-Averaging RIS Files / Batch
-
Generating Synthetic Data
-
Generate Temporal Segments / EEG
-Generate Temporal Segments / Inverse Space
-Oscillating Dipoles
+
EEG and Tracks
+
+ Exporting / Reprocessing Tracks
+ File Calculator
+ Averaging EEG Files / Interactive
Averaging EEG Files / Batch
+ Interpolating EEG Files
+ Segmentation of EEG Files
+ Fitting templates to EEG Files
Correlation / Coherence between files
Computing Templates / Centroids from cluster files
+ Creating ROIs from Tracks
+ Statistics on Tracks
Standardizing Tracks
Histogram of current EEG Tracks
Histogram of current EEG Time Frames
PCA on current EEG file
+
+
Frequency
+
+ Frequency Analysis of EEG Files
+ Averaging FREQ Files / Batch
+ Correlation / Coherence between files
+ Statistics on FREQ files
+
+
MRIs and Volumes
+
+ MRIs Preprocessing
+ Coregistering another MRI to current MRI
+ Skull Stripping Full Head MRIs
+ Brainstem Removal
+ Bias Field Correction
+ Extracting Grey Mask
+ Extracting Black / Grey / White Matters
+
+
Electrodes Coordinates and Solution Points
+
+ Coregistering Electrodes to Head MRI
+ Creating ROIs for Electrodes / Solution Points
+ Create a Template of Electrodes Coordinates
+ Transforming XYZ or SPI Set of Points
+
+
Inverse Solution
+
+ Creating Inverse Solution Matrices
+ Computing Results of Inverse Solutions
+ Results of Inverse Solutions to Volumes
+ + Statistics on + RIS files +
Standardizing existing RIS files
+ Averaging RIS Files / Batch
+
+
Generating Synthetic Data
+
+ Generate Temporal Segments / EEG
+ Generate Temporal Segments / Inverse Space
+ Oscillating Dipoles
-
+ -

File menu

-

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-

File | File Conversions sub-menu

 -

 

-
    -

    VRB to TVA

 -

To extract a trigger validation file .tva from the verbose - file .vrb of an Averaging.

-
    -

    FREQ to Tracks

 -

To batch split .freq files (3 dimensional) into tracks files - (2 dimensional), with one file per frequency.

-
    -

    Tracks to FREQ

 -

To batch fusion tracks file back into a .freq file.

-
    -

    FREQ to Spectrum

 -

To batch split .freq files (3 dimensional) into tracks files - (2 dimensional), with one file per spectrum.

-

File | Preferences | Files sub-menu

 -

 

-
    -

    Associate files with Cartool

 -

Restores all the file associations to the default of Cartool, f.ex. - associating .ep .eph files to directly open on double-click. 

-
    -

    Remove file association from Cartool

 -

Removes all the file associations made toward Cartool, you can not - double-click a file and it opens into Cartool anymore.

-

File | Preferences | Graphic sub-menu

 -

 

-
    -

    Harware Acceleration

 -

Auto: the default, Cartool tries to detect if you have an OpenGL - hardware implementation.

-

On: force using the OpenGL hardware implementation.

-

Off: force using the (very old) OpenGL software implementation of Windows.

-
    -

    3D Textures

 -

Auto: the default, Cartool tries to use 3D Textures for MRI display.

-

On: force using the 3D Textures for MRI display.

-

Off: force the 3D Textures for MRI display off. You might need this - if the MRI display does not work, like in some Virtual Machines.

-

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-   +

File menu

+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+

File | File Conversions sub-menu +

+

  +

+
    +

    VRB to TVA +

+

+ To extract a trigger validation file .tva from the verbose + file .vrb of an Averaging. +

+
    +

    FREQ to Tracks +

+

+ To batch split .freq files (3 dimensional) into tracks files + (2 dimensional), with one file per frequency. +

+
    +

    Tracks to FREQ +

+

To batch fusion tracks file back into a .freq file. +

+
    +

    FREQ to Spectrum +

+

+ To batch split .freq files (3 dimensional) into tracks files + (2 dimensional), with one file per spectrum. +

+

File | Preferences | Files sub-menu +

+

  +

+
    +

    Associate files with Cartool +

+

+ Restores all the file associations to the default of Cartool, f.ex. + associating .ep .eph files to directly open on double-click.  +

+
    +

    Remove file association from Cartool +

+

+ Removes all the file associations made toward Cartool, you can not + double-click a file and it opens into Cartool anymore. +

+

File | Preferences | Graphic sub-menu +

+

  +

+
    +

    Harware Acceleration +

+

+ Auto: the default, Cartool tries to detect if you have an OpenGL + hardware implementation. +

+

On: force using the OpenGL hardware implementation.

+

Off: force using the (very old) OpenGL software implementation of Windows. +

+
    +

    3D Textures +

+

Auto: the default, Cartool tries to use 3D Textures for MRI display.

+

On: force using the 3D Textures for MRI display.

+

+ Off: force the 3D Textures for MRI display off. You might need this + if the MRI display does not work, like in some Virtual Machines. +

+

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

\ No newline at end of file diff --git a/docs/ReferenceGuide/cartool-options.html b/docs/ReferenceGuide/cartool-options.html index 30f0e28e..df975d15 100644 --- a/docs/ReferenceGuide/cartool-options.html +++ b/docs/ReferenceGuide/cartool-options.html @@ -2,89 +2,127 @@ Appendix E - Cartool Options - -

- Appendix E
- Cartool Options

-

-  

-

- These options are called from the menu File - | Options.

-

-  

-

- Windows registry

- -

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-  

-

-   + +

+

+ Appendix E
+ Cartool Options +

+

+   +

+

+ These options are called from the menu + File + | Options + . +

+

+   +

+

+ Windows registry +

+ +

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

+

+   +

\ No newline at end of file diff --git a/docs/ReferenceGuide/cartool.css b/docs/ReferenceGuide/cartool.css index 147f303a..ede64919 100644 --- a/docs/ReferenceGuide/cartool.css +++ b/docs/ReferenceGuide/cartool.css @@ -1,6 +1,26 @@ /*-------------------- Cartool Reference Guide CSS */ +/*-------------------- All pages: page size limit and centering --------------------*/ + +body { + margin: 0; + padding: 0; + display: flex; + justify-content: center; /* Center the content horizontally */ + background-color: #f9f9f9; /* Optional: Background color */ + } + +.container { + width: 90%; /* Adjust width relative to the viewport */ + max-width: 1000px; /* Ensure a readable limit on larger screens */ + padding: 20px; /* Add padding for spacing */ + margin-top: 8px; /* Add space at the top */ + background-color: #ffffff; /* Optional: Background color */ + box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1); /* Optional: Add a subtle shadow */ + } + + /*-------------------- Headers --------------------*/ h1, .mvd-h1 { font-family:Arial,Verdana; diff --git a/docs/ReferenceGuide/command-line-interface.html b/docs/ReferenceGuide/command-line-interface.html index 5154c0e4..62495e01 100644 --- a/docs/ReferenceGuide/command-line-interface.html +++ b/docs/ReferenceGuide/command-line-interface.html @@ -8,177 +8,251 @@ } - -

- Command-Line Interface (CLI)

-

-  

-

- Cartool can be called directly from the command-line, either - from Windows batch files, Matlab or Python scripts, and therefor be called as a library - within external processing pipe-lines. To - finer control its behavior, you can pass it options and sub-commands, which - are described in this page.

-

-  

-
- CLI Syntax
-
- General Options
-
- Help & version
Main window - control
Children windows control
-
- Sub-Commands Options
-
- Registration
- Reprocess / Export Tracks
-

- CLI Syntax

-

- This will not be a full tutorial on the - CLI11 - Command-Line syntax, but just a few hints to help you get the job done:

- -

- General Options

-

- General options are used to control the - main window and children - windows appearance. It can also return a full, up-to-date - help syntax message in case you are - lost.

-

- Help & version

-

- To get the latest, up-to-date commands and syntax, you can always call:

- 
cartool64.exe --help
+ 
+     

+         

+             Command-Line Interface (CLI)
+         

+         

+              
+         

+         

+             Cartool can be called directly from the command-line, either
+             from Windows batch files, Matlab or Python scripts, and therefor be called as a library
+             within external processing pipe-lines. To
+             finer control its behavior, you can pass it options and sub-commands, which
+             are described in this page.
+         

+         

+              
+         

+         

+             CLI Syntax
+         

+         

+             General Options
+         

+         

+             Help & version

+                 Main window
+                 control
+             
Children windows control
+         

+         

+             Sub-Commands Options
+         

+         

+             Registration

+                 Reprocess / Export Tracks
+             
+         

+         

+             CLI Syntax
+         

+         

+             This will not be a full tutorial on the
+             
+                 CLI11
+                 Command-Line syntax
+             , but just a few hints to help you get the job done:
+         

+         
    
+             
  • Options can be either short, like "-h", or long, like "--help".
    • 
+             
  • Options are all case sensitives.
    • 
+             
  • 
+                 You'd better be providing files as full path,
+                 like  "D:\Data\MyFile.eeg"  and not as 
+                 "MyFile.eeg".
+             
    • 
+             
  • 
+                 Files with spaces in their names must be in double quotes, like 
+                 "D:\Data\My File with spaces.eeg".
+             
    • 
+             
  • 
+                 Files are to be specified at the end of the command-line, and prefixed
+                 with "--", like  "-- D:\Data\MyFile.eeg".
+             
    • 
+             
  • 
+                 An option showing f.ex.  {minimized,maximized,normal} 
+                 expects only one of these 3 values.
+             
    • 
+             
  • 
+                 An option showing f.ex.  [normal]  means this is the default
+                 value.
+             
    • 
+             
  • 
+                 A sub-command, like reprocesstracks, has a set of specific options not
+                 available elsewhere.
+             
    • 
+         

+         

+             General Options
+         

+         

+             General options are used to control the 
+                 main window and 
+                     children
+                     windows appearance
+                 
+             . It can also return a full, up-to-date
+             help syntax message in case you are
+             lost.
+         

+         

+             Help & version
+         

+         

+             To get the latest, up-to-date commands and syntax, you can always call:
+         

+         
cartool64.exe --help
  or
 cartool64.exe <subcommand> --help

-  

-   Current version can be retrieved with:

-  
cartool64.exe --version

-  

-   Main window control

-  

-   You can control the main window state, size and position with:

-  
cartool64.exe --mainwindow={minimized,maximized,normal} [maximized]
+         

+             Current version can be retrieved with:
+         

+         
cartool64.exe --version

+         

+             Main window control
+         

+         

+             You can control the main window state, size and position with:
+         

+         
cartool64.exe --mainwindow={minimized,maximized,normal} [maximized]
               --mainwindowsize=width,height
               --mainwindowpos=x,y

-  

-   You can skip the splash-screen with:

-  
cartool64.exe --nosplash

-  

-   And you can even select which monitor to open Cartool to:

-  
cartool64.exe --monitor=<number>

-  

-   Note that the monitor index might differ from what the Control Panel shows 
-   you, though. This is a Windows thing, sorry about that...

-  

-    

-  

-   Examples:

-  

-   Opening Cartool on the top left part of the screen, resized for HD:

-  
cartool64.exe --mainwindowpos=0,0 --mainwindowsize=1920,1080

-  

-   Fast opening Cartool full screen on a second monitor:

-  
cartool64.exe --mainwindow=maximized --monitor=2 --nosplash

-  

-   Children windows control

-  

-   You can control every new child window state, size and position 
-   by using any of these options before a given file (note the 
-   "--" before the files):

-  
cartool64.exe --childwindow={minimized,maximized,normal} [normal]
+         

+             You can skip the splash-screen with:
+         

+         
cartool64.exe --nosplash

+         

+             And you can even select which monitor to open Cartool to:
+         

+         
cartool64.exe --monitor=<number>

+         

+             Note that the monitor index might differ from what the Control Panel shows
+             you, though. This is a Windows thing, sorry about that...
+         

+         

+              
+         

+         

+             Examples:
+         

+         

+             Opening Cartool on the top left part of the screen, resized for HD:
+         

+         
cartool64.exe --mainwindowpos=0,0 --mainwindowsize=1920,1080

+         

+             Fast opening Cartool full screen on a second monitor:
+         

+         
cartool64.exe --mainwindow=maximized --monitor=2 --nosplash

+         

+             Children windows control
+         

+         

+             You can control every new child window state, size and position
+             by using any of these options before a given file (note the
+             "--" before the files):
+         

+         
cartool64.exe --childwindow={minimized,maximized,normal} [normal]
               --childwindowsize=width,height
               --childwindowpos=x,y
               -- <files>

-  

-   Each of these parameters could be repeated for each file 
-   with different values. In case some parameters are missing, the last valid 
-   ones will be used.

-  

-   Also note that, for the moment, you can not specify any parameter for the 
-   nth file without specifying 
-   the parameters of all previous files!

-  

-   Examples:

-  

-   Single file opened maximized:

-  
cartool64.exe --childwindow=maximized -- <file1>

-  

-   First file opened normally, next one opened minimized:

-  
cartool64.exe --childwindow=normal -- <file1> --childwindow=minimized -- <file2>
+         

+             Each of these parameters could be repeated for each file
+             with different values. In case some parameters are missing, the last valid
+             ones will be used.
+         

+         

+             Also note that, for the moment, you can not specify any parameter for the 
+                 nth
+              file without specifying
+             the parameters of all previous files!
+         

+         

+             Examples:
+         

+         

+             Single file opened maximized:
+         

+         
cartool64.exe --childwindow=maximized -- <file1>

+         

+             First file opened normally, next one opened minimized:
+         

+         
cartool64.exe --childwindow=normal -- <file1> --childwindow=minimized -- <file2>
  or
 cartool64.exe --childwindow=normal minimized -- <file1> <file2>

-  

-   First file opened normally, 2 successive files opened minimized:

-  
cartool64.exe --childwindow=normal -- <file1> --childwindow=minimized -- <file2> <file3>

-  

-   First file opened normally, 2 successive files opened minimized, last one 
-   opened maximized:

-  
cartool64.exe --childwindow=normal minimized minimized maximized  -- <file1> <file2> <file3> <file4>

-  

-   Single file opened normally, with overridden size and position:

-  
cartool64.exe --childwindowsize=500,250 --childwindowpos=0,0 -- <file1>

-  

-   Single file resized and repositionned, then minimized:

-  
cartool64.exe --childwindow=minimized --childwindowsize=500,250 --childwindowpos=0,0 -- <file1>

-  

-   Two files opened normally, with overridden sizes and positions:

-  
cartool64.exe --childwindowsize=500,250 200,800 --childwindowpos=0,0 500,250 -- <file1> <file2>

-  

-   Sub-Commands Options

-  

-   Sub-commands allow to run a specific toolbox or 
-   processing of Cartool. Each sub-command has its own set of options, 
-   which are therefor not available to other sub-commands. Sub-commands 
-   still can use some of the general options, 
-   though.

-  

-   Registration

-  

-   Registering Cartool to Windows allows for double-click file opening, 
-   icons and files associations etc... These associations are silently set for 
-   you by the Cartool installer, once and for all. But if anything gets corrupted, 
-   like erroneous icons and files associations, it is possible to invoke this 
-   registration manually. Still not an everyday manoeuvre, though...

-  

-   Registration is a sub-command, with only one of these exclusive 
-   options:

-  
cartool64.exe register --{yes,no,reset,help}

-  

-   Also note that upon execution, Cartool will exit straight away. It might be 
-   necessary to reboot your machine if things get confusing for Windows, though 
-   most of the time, you need not.

-  

-   Reprocess / Export Tracks

-  

-   This sub-command corresponds to the 
-   Reprocess / Export Tracks Dialog.

-  

-   Getting the Reprocess / Export Tracks subcommand full syntax with:

-  
cartool64.exe reprocesstracks --help

-  

-   Which gives:

-  
Re-process / Export tracks command
+         

+             First file opened normally, 2 successive files opened minimized:
+         

+         
cartool64.exe --childwindow=normal -- <file1> --childwindow=minimized -- <file2> <file3>

+         

+             First file opened normally, 2 successive files opened minimized, last one
+             opened maximized:
+         

+         
cartool64.exe --childwindow=normal minimized minimized maximized  -- <file1> <file2> <file3> <file4>

+         

+             Single file opened normally, with overridden size and position:
+         

+         
cartool64.exe --childwindowsize=500,250 --childwindowpos=0,0 -- <file1>

+         

+             Single file resized and repositionned, then minimized:
+         

+         
cartool64.exe --childwindow=minimized --childwindowsize=500,250 --childwindowpos=0,0 -- <file1>

+         

+             Two files opened normally, with overridden sizes and positions:
+         

+         
cartool64.exe --childwindowsize=500,250 200,800 --childwindowpos=0,0 500,250 -- <file1> <file2>

+         

+             Sub-Commands Options
+         

+         

+             Sub-commands allow to run a specific toolbox or
+             processing of Cartool. Each sub-command has its own set of options,
+             which are therefor not available to other sub-commands. Sub-commands
+             still can use some of the general options,
+             though.
+         

+         

+             Registration
+         

+         

+             Registering Cartool to Windows allows for double-click file opening,
+             icons and files associations etc... These associations are silently set for
+             you by the Cartool installer, once and for all. But if anything gets corrupted,
+             like erroneous icons and files associations, it is possible to invoke this
+             registration manually. Still not an everyday manoeuvre, though...
+         

+         

+             Registration is a sub-command, with 
+                 only one of these exclusive
+                 options
+             :
+         

+         
cartool64.exe register --{yes,no,reset,help}

+         

+             Also note that upon execution, Cartool will exit straight away. It might be
+             necessary to reboot your machine if things get confusing for Windows, though
+             most of the time, you need not.
+         

+         

+             Reprocess / Export Tracks
+         

+         

+             This sub-command corresponds to the 
+                 
+                     Reprocess / Export Tracks Dialog
+                 
+             .
+         

+         

+             Getting the Reprocess / Export Tracks subcommand full syntax with:
+         

+         
cartool64.exe reprocesstracks --help

+         

+             Which gives:
+         

+         
Re-process / Export tracks command
 Usage: reprocesstracks [OPTIONS]
 
 Options:
@@ -234,157 +308,229 @@ 

 --nomarkers 			Not saving the markers to file
 --concatenate 			Concatenate all output into a single file
 -h,--help 			This message

-  

-   Notes:

-  
    
-	  
  •  You can combine most of these options, as long 
-	  as they make sense to you!
    • 
-	  
  • Options will be applied sequentially according to their 
-	  relative appearance in the help message above. Which also 
-	  corresponds to their top-down appearance within the
-	  Reprocess / Export Tracks Dialog.
    
-	  This means f.ex. that filters will be applied first, followed by the new 
-	  reference, then the baseline correction, etc...
    • 
-	  
  • Likewise, filters are applied following their top-down 
-	  appearance within the EEG 
-	  Filters dialog.
    • 
-	  
  • Be careful not to overwrite existing files. Usually, 
-	  you are on the safe side if you provide a relevant --infix 
-	  option.
    • 
-  

-  

-   Butterworth filters

-  

-   Band-Pass option excludes both High-Pass and Low-Pass options. However, it is 
-   currently allowed to specify both High-Pass and 
-   Low-Pass options, which will be internally combined into a proper High-Pass.

-  

-   For a single High-Pass or Low-Pass filter, the order, 
-   if overridden, must be an even value. Current default value 
-   is 8.

-  

-   For a Band-Pass filter, the order must be a multiple 
-   of 4, as it basically sums up the high and low pass orders together. 
-   Which means the default is 8+8=16. Note that this does not follow 
-   the Matlab convention, which would erroneously show 8 instead...

-  

-   Examples:

-  

-   Saving files to another format, f.ex. to BrainVision .eeg:

-  
cartool64.exe reprocesstracks --infix=NewExt --ext=eeg -- <file1> <file2> <file3>

-  

-   Renaming the electrodes, "borrowing" actual names from a .xyz 
-   file:

-  
cartool64.exe reprocesstracks --xyzfile=electrodesfile.xyz --infix=Renamed --ext=eeg -- <file1> <file2> <file3>

-  

-   Cropping the time range, from time frame 100 to 499; cropping from time frame 
-   200 up to end-of-file (note the missing --timemax option in the 
-   latter case):

-  
cartool64.exe reprocesstracks --timemin=100 --timemax=499 --infix=Cropped -- <file1> <file2> <file3>
+         

+             Notes:
+         

+         
    
+             
  • 
+                  You can combine most of these options, as long
+                 as they make sense to you!
+             
    • 
+             
  • 
+                 Options will be applied sequentially according to 
+                     their
+                     relative appearance in the help message above
+                 . Which also
+                 corresponds to their top-down appearance within the
+                 Reprocess / Export Tracks Dialog.
    
+                 This means f.ex. that filters will be applied first, followed by the new
+                 reference, then the baseline correction, etc...
+             
    • 
+             
  • 
+                 Likewise, filters are applied following their 
+                     top-down
+                     appearance within the
+                 
+                     
+                         EEG
+                         Filters dialog
+                     
+                 .
+             
    • 
+             
  • 
+                 Be careful not to overwrite existing files. Usually,
+                 you are on the safe side if you provide a relevant --infix
+                 option.
+             
    • 
+         

+         

+             Butterworth filters
+         

+         

+             Band-Pass option excludes both High-Pass and Low-Pass options. However, it is
+             currently allowed to specify both High-Pass and 
+             Low-Pass options, which will be internally combined into a proper High-Pass.
+         

+         

+             For a single High-Pass or Low-Pass filter, the order,
+             if overridden, must be an even value. Current default value
+             is 8.
+         

+         

+             For a Band-Pass filter, the order must be a 
+                 multiple
+                 of 4
+             , as it basically sums up the high and low pass orders together.
+             Which means the default is 8+8=16. Note that this does not follow
+             the Matlab convention, which would erroneously show 8 instead...
+         

+         

+             Examples:
+         

+         

+             Saving files to another format, f.ex. to BrainVision .eeg:
+         

+         
cartool64.exe reprocesstracks --infix=NewExt --ext=eeg -- <file1> <file2> <file3>

+         

+             Renaming the electrodes, "borrowing" actual names from a .xyz
+             file:
+         

+         
cartool64.exe reprocesstracks --xyzfile=electrodesfile.xyz --infix=Renamed --ext=eeg -- <file1> <file2> <file3>

+         

+             Cropping the time range, from time frame 100 to 499; cropping from time frame
+             200 up to end-of-file (note the missing --timemax option in the
+             latter case):
+         

+         
cartool64.exe reprocesstracks --timemin=100 --timemax=499 --infix=Cropped -- <file1> <file2> <file3>
 cartool64.exe reprocesstracks --timemin=200 --infix=Cropped -- <file1> <file2> <file3>

-  

-   Keeping only some epochs, labelled as "Good" markers, from the time line:

-  
cartool64.exe reprocesstracks --keeptriggers=Good --infix=OnlyGoodies -- <file1> <file2> <file3>

-  

-   Deleting some epochs, labelled as "Bad" or "Blink" markers, from the time 
-   line:

-  
cartool64.exe reprocesstracks --excludetriggers=Bad,Blink --infix=NoBaddies -- <file1> <file2> <file3>

-  

-   Appending a null track called "MyRef":

-  
cartool64.exe reprocesstracks --nulltracks=MyRef --infix=Nullos -- <file1> <file2> <file3>

-  

-   Changing the reference to Cz, using a
-   .xyz file to get the names right; setting an
-   Average Reference:

-  
cartool64.exe reprocesstracks --xyzfile=electrodesfile.xyz --reference=Cz --Infix=RefCz -- <file1> <file2> <file3>
+         

+             Keeping only some epochs, labelled as "Good" markers, from the time line:
+         

+         
cartool64.exe reprocesstracks --keeptriggers=Good --infix=OnlyGoodies -- <file1> <file2> <file3>

+         

+             Deleting some epochs, labelled as "Bad" or "Blink" markers, from the time
+             line:
+         

+         
cartool64.exe reprocesstracks --excludetriggers=Bad,Blink --infix=NoBaddies -- <file1> <file2> <file3>

+         

+             Appending a null track called "MyRef":
+         

+         
cartool64.exe reprocesstracks --nulltracks=MyRef --infix=Nullos -- <file1> <file2> <file3>

+         

+             Changing the reference to Cz, using a
+             .xyz file to get the names right; setting an
+             Average Reference:
+         

+         
cartool64.exe reprocesstracks --xyzfile=electrodesfile.xyz --reference=Cz --Infix=RefCz -- <file1> <file2> <file3>
 cartool64.exe reprocesstracks --reference=average --Infix=RefAvg -- <file1> <file2> <file3>

-  

-   Downsampling files by a factor of 4, f.ex. from a sampling frequency of 1000 
-   Hz down to 250 Hz:

-  
cartool64.exe reprocesstracks --downsampling=4 --infix=Down -- <file1> <file2> <file3>

-  

-   Concatenating files into a single file:

-  
cartool64.exe reprocesstracks --concatenate --infix=Concat -- <file1> <file2> <file3>

-  

-   You have access to all the filters from the 
-   EEG Filters Dialog.

-  

-   For example, a typical band-pass for EEG (note the DC removal, for safety 
-   reasons):

-  
cartool64.exe reprocesstracks --dc --bandpass=1,40 --notch=50 --harmonics --order=16 --infix=BandPass -- <file1> <file2> <file3>

-  

-   Applying the default Spatial Filter 
-   of Cartool. Attention to the EEG and XYZ dimensions, which sould match 
-   exactly, especially if you added some null tracks:

-  
cartool64.exe reprocesstracks --xyzfile=electrodesfile.xyz --spatialfilter --infix=Spatial -- <file1> <file2> <file3>

-  

-   Applying some rectification + envelope, with a time window of 100ms:

-  
cartool64.exe reprocesstracks --rectification=power --envelope=100 --infix=Envelope -- <file1> <file2> <file3>

-  

-   Thresholding the data, ranking and keeping data above 0.95; keeping data 
-   either below -1 or above 1; keeping data above -1 
-   and below 1:

-  
cartool64.exe reprocesstracks --ranking --keepabove=0.95 --infix=Significant5 -- <file1> <file2> <file3>
+         

+             Downsampling files by a factor of 4, f.ex. from a sampling frequency of 1000
+             Hz down to 250 Hz:
+         

+         
cartool64.exe reprocesstracks --downsampling=4 --infix=Down -- <file1> <file2> <file3>

+         

+             Concatenating files into a single file:
+         

+         
cartool64.exe reprocesstracks --concatenate --infix=Concat -- <file1> <file2> <file3>

+         

+             You have access to 
+                 all the filters from the 
+                     EEG Filters Dialog
+                 
+             .
+         

+         

+             For example, a typical band-pass for EEG (note the DC removal, for safety
+             reasons):
+         

+         
cartool64.exe reprocesstracks --dc --bandpass=1,40 --notch=50 --harmonics --order=16 --infix=BandPass -- <file1> <file2> <file3>

+         

+             Applying the default Spatial Filter
+             of Cartool. Attention to the EEG and XYZ dimensions, which sould match
+             exactly, especially if you added some null tracks:
+         

+         
cartool64.exe reprocesstracks --xyzfile=electrodesfile.xyz --spatialfilter --infix=Spatial -- <file1> <file2> <file3>

+         

+             Applying some rectification + envelope, with a time window of 100ms:
+         

+         
cartool64.exe reprocesstracks --rectification=power --envelope=100 --infix=Envelope -- <file1> <file2> <file3>

+         

+             Thresholding the data, ranking and keeping data above 0.95; keeping data
+             either below -1 or above 1; keeping data above -1 
+                 and
+              below 1:
+         

+         
cartool64.exe reprocesstracks --ranking --keepabove=0.95 --infix=Significant5 -- <file1> <file2> <file3>
 cartool64.exe reprocesstracks --keepbelow=-1 --keepabove=1 --infix=OutsideInterval -- <file1> <file2> <file3>
 cartool64.exe reprocesstracks --keepabove=-1 --keepbelow=1 --infix=InsideInterval -- <file1> <file2> <file3>

-  

-    

-  

-    

-  

-    

-  

-    

-  
 

-  
 

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-    

-    

-    
+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         
 

+         
 

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+              
+         

+              
+         

+              
+     

  
 
\ No newline at end of file
diff --git a/docs/ReferenceGuide/computing-erps.html b/docs/ReferenceGuide/computing-erps.html
index e570bfa5..33481bf1 100644
--- a/docs/ReferenceGuide/computing-erps.html
+++ b/docs/ReferenceGuide/computing-erps.html
@@ -8,2409 +8,3166 @@
 }
 
  
- 
-  

-   Computing ERPs and Averaging Tracks Files

-  

-    

-  

-   What is averaging files?

-  

-   How to run the averaging process

-  
-  

-   Results

-  
-  

-   What is "averaging files"?

-  

-   This is a semi-automated tool to average and / or exports
-    epochs from EEG file(s).

-  

-   The user sets some parameters to control more or less tightly the 
-   averaging process, and then has to pilot the averaging 
-   (because we want you to have a look to your data!). It is used to 
-   compute either ERPs, Grand Means, but also to split 
-   a file into epochs.

-  

-   Files that can be processed could be any Spontaneous
-    EEG recordings or ERPs,
-    but also Frequency transforms 
-   or Results of Inverse Solution.

-  

-   How to run the averaging process

-  

-   Called from the Tools
-    | Averaging files menu, there are three dialogs for 
-   the parameters. Then, when enough parameters are given and after 
-   pressing the Process button, the control dialog appears to 
-   monitor the averaging process.

-  

-    

-  
-  

-   Input Files dialog

-  

-   

-    

-   

-  

-   
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-   

-      

-       Input Files

-      

-        

-      

-       Input Files

-      

-       A combo-box used to enter which
-        files to average:

-      
    
-       
  • 
-       
    
-        the edit field (on top) contains the next file to be added
    
-        
  • the list field (below) contains the files 
-        already added
    
-       

-      

-       Either type or modify the file name in the Edit field, or rather use 
-       the Browse button to select a set of files with a file dialog.

-       Then see Add Edit Line from Lists, 
-       and Drag & Drop.

-      

-       Session

-      

-       Specify an optional session number for the next file to be added. Let 
-       it empty if there are no sessions, or if you don't know (though you should!).

-       When Cartool will encounter that file, and if it sees something wrong 
-       with the specified session, it will prompt you for the right session.

-      

-       Trigger Validation Files (optional)

-      

-       An optional .tva 
-       file, used to filter out some of the triggers / markers. F.ex. 
-       excluding the false responses from an experiment, or if you 
-       wish to re-do an averaging and to use exactly the same accepted / 
-       rejected triggers.

-      

-       Also available in these files is the Reaction Time, which you
-        can use here in the averaging.

-      

-       Triggers / Markers

-      

-       The list of triggers / markers 
-       names to be averaged, separated either by a space, a comma or a 
-       semicolumn (but please, just use only one type of separator for the 
-       sake of clarity!), f.ex.:  On Off 1 2 3 4

-      

-       Trigger names that contain a space should be put between double 
-       quotes, f.ex. "eye blink".

-      

-       Wildchars are allowed with the following restrictions:

-      
    
-       
  • 
-       
    
-        Use  *  to specify all 
-        triggers / markers, Cartool will properly expand it with the 
-        trigger names actually found in each file, one at a time.
    
-        
  • Use  Foo*  
-        to select all triggers that starts with the letters "Foo" 
-        (case insensitive). F.ex. all correlations between 0.80 to 1.00: Corr8* Corr9* Corr100
    
-        
  • All other uses are not recognized yet (more than 
-        one *, or the * at the beginning).

-      

-       Use Drag & Drop to quickly add files

-      

-       This is only to remind the user of the very convenient Drag
-        & Drop feature.

-      

-       Add Edit Line from Lists

-      

-       When all the edit
-        fields have been filled, and in order to validate them, click on 
-       this button to transfer their values into their corresponding list 
-       fields (below).

-      

-       If the Session or Trigger Validation Files edit fields 
-       were left empty, an empty entry is added.

-       But if the Triggers / Markers edit field is empty, a * 
-       will be added instead, to use all the triggers / markers.

-      

-       After the edit fields have been transfered, they are all cleared for 
-       the next input, except the Triggers / Markers edit field, so 
-       you can re-use the same triggers again.

-      

-       Remove Last Edit Line from Lists

-      

-       Pops the last added line from the lists back to the edit fields, 
-       either to remove the line, or to modify it and insert it again.

-       By pressing it many times, you also clear out the lists step by step.

-      

-       Replace Current Selected Field

-      

-       First, click on any item in any of the lists (input files, session, 
-       tva, triggers / markers). Its content will appear in its 
-       corresponding edit field (on top) for you to modify it.

-       Once modified, click on this button to update the originating list 
-       with this very new value, and its done!

-      

-       This is a very practical way to modify the input lists wihtout having 
-       to deconstruct the whole of them (changing only the triggers, the 
-       session, or the files...).

-      

-       Clear All Lists

-      

-       To clear out all the lists at once.

-      

-       Read Lists from File

-      

-       You can directly add a whole set of files to average, 
-       optionally including the session, tva and triggers / markers. Either 
-       you constructed these lists yourself 
-       beforehand, or they were previously saved 
-       by Cartool.

-      

-       Note that the lists are simply augmented, and not replaced. If you 
-       want to do so, clear them out first.

-       See also Drag & Drop.

-      

-       Write Lists to File

-      

-       You can save the current lists into a 
-       file, in case you want to re-use them.

-       See the file formats available.

-      

-       Options

-      

-        

-      

-       Types of triggers to consider

-      

-       Cartool currently distinguishes these three types of triggers:

-      
-      

-       Here you can select which ones (and only these) you want to use in 
-       the averaging.

-       You can also select more than one type, and at least one.

-      

-       Be aware that not selecting a given type (markers f.ex.) will 
-       make all of them invisible during the averaging process! This, 
-       however, could be very useful, f.ex. if you have duplicate names 
-       between triggers and markers and don't want to mix them.

-      

-       Electrodes Coordinates file

-      

-       You can optionally specify the 3D coordinates
-        of the electrodes to see a map 
-       of the current epoch to be averaged.

-       Also, in this case, a new coordinate file will be outputed with only 
-       the electrodes that will be actually saved in the averaged file 
-       (f.ex. to be used for interpolation 
-       or display of maps).

-      

-       Output Base File Name

-      

-       Specify here a basis for all the file names that will be 
-       generated during the averaging process.

-      

-       Cartool automatically provides you with a smart base file name that 
-       is a compound of the part common to all the files to be averaged 
-       (f.ex. "01conditionthis" and "02conditionthat" 
-       will give "condition"), added with a list of all the 
-       triggers used (f.ex. 1, 2 and 3 will give "123", resulting 
-       to the base file name "condition.123"). Well, it's easier 
-       to see it in action!

-      

-       You can override the base file name, either to simplify it, to fit it 
-       to your own taste, or to avoid overwriting files...

-      

-       << Previous  |  Next >>

-      

-       Use these buttons to navigate through the previous and next dialogs 
-       (if any).

-      

-       See which current dialog you are in, and to which other dialogs you 
-       connect, in the tab-like part at the top of the dialog under 
-       the title.

-      

-       These buttons are enabled if the parameters of the current 
-       dialog are OK. If they don't (not enough informations, 
-       inconsistent ones, etc...), or if there is no neighboring dialog to 
-       switch to, some of these buttons are disabled.

-      

-       Process

-      

-       This button actually launches the averaging process.

-      

-       This button remains disabled until all the parameter 
-       dialogs have received enough (and consistent) informations. If 
-       this is not the case, first check the current dialog: if its 
-       "Next" button is disabled, the problem is in the current 
-       dialog. Otherwise, browse the other dialogs for some missing informations.

-      

-       Cancel

-      

-       Quit the dialog.

-      

-       Help

-      

-       Launch the Help to the right page (should be here...).

-  

-    

-  

-   Input Files dialog - Technical points & hints

-  

-   File types that can be averaged:

-  
-  

-   Pre-filling the Triggers / Markers field

-  

-   Before entering more than one EEG file (by Drag
-    & Drop f.ex.), it can be very convenient to enter the 
-   triggers / markers code in the edit field. All subsequent EEG file 
-   will inherited these informations. Of course, you can later change
-    / edit all these informations.

-  

-   Sessions

-  

-   There is no problem to use the same file many times in a row, usually 
-   if it contains multiple sessions. In this case, specify the session 
-   number for each input line.

-  

-   You can Drag & Drop these files 
-   directly from the Explorer:

-  
-  

-   File formats to save or retrieve the 
-   list of files to average and their parameters:

-  
-  

-   Parameters dialog

-  

-   

-    

-   

-  

-   
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-       
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-       
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-   

-      

-       Parameters

-      

-        

-      

-       Presets:

-      

-       This is handy to quickly set the main parameters according to the 
-       most frequent uses, listed in the drop-down box.

-      

-       The most important parameters will be set, still some 
-       parameters have to be set manually! And, as usual, double 
-       check that all your settings make sense...

-      

-       Retrieve parameters from .vrb file

-      

-       Give a .vrb file 
-       generated from a previous averaging process, it will be scanned and 
-       as much parameters as possible will be retrieved and restored.

-      

-       This facility will work only with .vrb files compatible 
-       with this version of Cartool. Anyway, check that the parameters you 
-       get are the one you expected!

-      

-       You can also simply Drop the .vrb file into the dialog.

-      

-       Channel Checking

-      

-        

-      

-       Regular channels:

-      

-       The next parameters concern only the EEG channels.

-      

-       Test to Threshold Value:

-      

-       When selected, you have to specify the threshold above which a channel 
-       will be considered as bad / corrupted.

-      

-       See channel checking.

-      

-       Exclude these Channels from Test:

-      

-       If you already know what channels were noisy or inactive, you can 
-       fill this field to avoid testing them. Still, you can exclude 
-       channels later on, during the averaging process.

-      

-       See channel checking.

-      

-       Auxiliary channels:

-      

-       The next parameters concern only the auxiliary channels (ECG, eyes, etc...).

-      

-       Test to Threshold Value:

-      

-       When selected, you have to specify the threshold above which an auxiliary
-        channel will be considered as bad / corrputed.

-      

-       See channel checking.

-      

-       Override the Auxiliaries with:

-      

-       Override the default auxiliary channels.
-        The list you provide will completely supersede the default one.

-      

-       Time Interval

-      

-        

-      

-       Epoch Origin:

-      

-       Choose the time origin of the epochs. 
-       See length and origin position.

-      

-       Fixed Time Frame

-      

-       One and only one TF, at a 
-       fixed position. Useful for grand averages.

-      

-       Trigger

-      

-       The triggers / markers (actually, their onset).

-      

-       Trigger + Offset

-      

-       The triggers / markers, plus a given and fixed number of TFs.

-      

-       Trigger + Reaction Time

-      

-       The triggers / markers plus a variable step found in the .tva 
-       file (specified in the files dialog).

-      

-       Attention: the steps are in milliseconds, not TFs!

-      

-       Duration

-      

-       The length of the epoch.

-      

-       Pre-Frames Duration:

-      

-       The number of time frames before the origin (positive number, 
-       or 0). See length and origin position.

-      

-       Post-Frames Duration:

-      

-       The number of time frames after the origin (positive number, 
-       or 0). See length and origin position.

-      

-       Total Frames Duration:

-      

-       The total number of time frames. See length 
-       and origin position.

-      

-       Note that the TF values are also converted into milliseconds if a 
-       sampling frequency has been found in the files to average.

-      

-       Computation Parameters

-      

-       These parameters are applied according to the following sequence.

-      

-       Data Type:

-      

-        

-      

-       Only Positive

-      

-       Data consist of positive only, scalar data. This could be 
-       spikes from neuron recordings, or the Results of Inverse Solution, f.ex.

-      

-       This will logically turn off the Polarity & References options.

-      

-       See this point on 
-       positive data and also this point.

-      

-       Signed

-      

-       Signed scalar values, like, you know, EEG.

-      

-       Data reference

-      

-        

-      

-       No Reference

-      

-       Data are used as they come from files, no changes occur.

-      

-       Average Reference

-      

-       Data are average reference-d, can be 
-       used for Grand Averages but not necessarily.

-      

-       Maps / Patterns Polarity:

-      

-        

-      

-       Ignore

-      

-       Polarity of maps does not matter, so ignore it. Inverted maps are 
-       considered the same (same underlying generators, but with reversed polarity).

-      

-       Used for spontaneous EEG recordings or FFT
-        Approximation.

-      

-       Account

-      

-       Polarity of maps matter, that is, inverted maps are indeed considered 
-       as different.

-      

-       Used for ERPs.

-      

-       Using Filters:

-      

-       Clicking on this button brings the usual Filter
-        Dialog. Fill it according to your needs, and specify a sampling 
-       frequency if none was found after getting the 
-       input files.

-      

-       Clicking on the button again turns the filters off.

-      

-       You can refine on what the filters should be applied to (see 
-       the possible combinations):

-      

-       on Results

-      

-       On the outputted data.

-      

-       on Display

-      

-       On the EEG display.

-      

-       Baseline Correction:

-      

-       Check this button if you want to apply some baseline correction 
-       (subtracting each track with its average within a given time period).

-      

-       Inferior Limit:

-      

-       Lower boundary as on offset to the epoch origin.

-      

-       Use negative values before the origin, positive values after.

-      

-       Superior Limit:

-      

-       Superior boundary as on offset to the epoch origin.

-       Use negative values before the origin, positive values after.

-      

-       The limits specified need not to be within the range of 
-       the Pre and Post-Frames. They can be whatever
-        you wish, Cartool will handle all the cases gracefully.

-      

-       When changing the "Pre-Frames Duration" value, the 
-       "Baseline Inferior Limit" will be updated automatically.

-      

-       Excluding Bad Epochs

-      

-       Check this button to allow skipping bad 
-	   epochs.

-      

-       at Markers:

-      

-       Specify the exact marker names of epochs to be skipped.

-       The markers should have been already set 
-	   either manually, or by scanning automatically the tracks.

-       Any averaging epoch intersecting 
-	   with any of these bad markers will be automatically 
-	   skipped.

-      

-       Accepting All Remaining Epochs

-      

-       Automatically accept all epochs for all files. 
-	   Any specified thresholding tests will be 
-	   skipped.

-      

-       However, if Excluding Bad Epochs have 
-	   been specified, then it will accept only the non-overlapping epochs only.

-	  

-       This option is however more useful for Grand Averages, where you just 
-	   want to sum files you already know and trust.

-      

-       Notice that no TVA file will be 
-       outputted, as for Grand Means we don't care...

-      

-       << Previous  |  Next >>

-      

-       Use these buttons to navigate through the previous and next dialogs 
-       (if any).

-      

-       See which current dialog you are in, and to which other dialogs you 
-       connect, in the tab-like part at the top of the dialog under 
-       the title.

-      

-       These buttons are enabled if the parameters of the current 
-       dialog are OK. If they don't (not enough informations, 
-       inconsistent ones, etc...), or if there is no neighboring dialog to 
-       switch to, some of these buttons are disabled.

-      

-       Process

-      

-       This button actually launches the averaging process.

-      

-       This button remains disabled until all the parameter 
-       dialogs have received enough (and consistent) informations. If 
-       this is not the case, first check the current dialog: if its 
-       "Next" button is disabled, the problem is in the current 
-       dialog. Otherwise, browse the other dialogs for some missing informations.

-      

-       Cancel

-      

-       Quit the dialog.

-      

-       Help

-      

-       Launch the Help to the right page (should be here...).

-  

-    

-  

-   Parameters dialog - Technical points & hints

-  

-   Channel checking:

-  
-  
 

-  
The time interval used for testing a given epoch is the 
-  following:

-  
-  

-   Overriding the auxiliaries :

-  
-  

-   Position of the origin, and length of 
-   the output file:

-  
-  

-   

-    
-     
-      
-      
-      
-      
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-      
-      
-      
-      
-     
-    

-       

-        

-         Epoch origin

-       

-        

-         Last TF of epoch

-       

-        Offset in original file, in TF

-       

-        

-         0

-       

-        

-         1

-       

-        

-         2

-       

-        

-         . . . . .

-       

-        

-         247

-       

-        

-         248

-       

-        

-         249

-       

-        Absolute TF position in output file

-       

-        

-         0

-       

-        

-         1

-       

-        

-         2

-       

-        

-         . . . . .

-       

-        

-         247

-       

-        

-         248

-       

-        

-         249

-   

-  
-  

-   

-    
-     
-      
-      
-      
-      
-      
-      
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-      
-      
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-      
-      
-      
-      
-      
-      
-     
-    

-       

-        

-         First TF of epoch

-       

-        

-         Epoch origin

-       

-        

-         Last TF of epoch

-       

-        Offset in original file, in TF

-       

-        

-         -50

-       

-        

-         -49

-       

-        

-         ...

-       

-        

-         -1

-       

-        

-         0

-       

-        

-         1

-       

-        

-         ...

-       

-        

-         248

-       

-        

-         249

-       

-        Absolute TF position in output file

-       

-        

-         0

-       

-        

-         1

-       

-        

-         ...

-       

-        

-         49

-       

-        

-         50

-       

-        

-         51

-       

-        

-         ...

-       

-        

-         298

-       

-        

-         299

-   

-  
-  

-   Channels filtering:

-  
-  

-   Ignoring Maps Polarity

-  

-   For each TF sequentially, take all the maps for all the epochs 
-   and check if they correlate negatively with the map with the 
-   highest GFP. Then invert (multiply by -1) these maps before 
-   proceeding to the next step of the averaging (usually the summation, 
-   saving epoch to file, etc...).

-  

-   This way, we will sum maps with the same "polarity".

-  

-   Excluding Bad Epochs

-  
-  

-   Output Files dialog

-  

-   

-    

-   

-  

-   
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-   

-      

-       Output Files

-      

-        

-      

-       Merging / Splitting Triggers

-      

-       Choose how to handle the accepted epochs:

-      

-       According to Trigger Values, accepted epochs are:

-      

-        

-      

-       Merged into One File

-      

-       All epochs are averaged into a single file, whatever their trigger codes.

-      

-       If there are triggers 1, 2, 3, 4, the result will be a single file 
-       that sums all these epochs.

-      

-       Split into Separate Files

-      

-       The epochs are routed to different files 
-       according to their trigger codes.

-      

-       Epochs from trigger 1 are summed in their own file, and so on with 
-       epochs from triggers 2, 3 and 4.

-      

-       The standard error and standard deviation can also be computed on 
-       these files (if these options are selected, of course).

-      

-       You can select both the Merge and the Split options.

-      

-       Data Computed

-      

-        

-      

-       Average of Epochs

-      

-       Compute and save the average of the accepted epochs. This is usually 
-       what you came for!

-      

-       Applies both to the Merged and Split files.

-      

-       Sum of Epochs

-      

-       Compute and save the sum of the accepted epochs.

-      

-       Applies both to the Merged and Split files.

-      

-       Also see this note.

-      

-       Standard Deviation

-      

-       Compute and save the standard deviation of the accepted epochs.

-      

-       Applies both to the Merged and Split files.

-      

-       Standard Error

-      

-       Compute and save the standard error of the accepted epochs.

-      

-       Applies both to the Merged and Split files.

-      

-       1 File per Epoch

-      

-       Save the accepted epochs, each epoch 
-       being put into a separate file.

-      

-       This is done only once, and is not relevant if epochs are Merged
-        or Split.

-       A single marker is added for each file, with the trigger code 
-	   of the current epoch, at the correct pre-stimulus offset.

-      

-       All Epochs in 1 File

-      

-       Save the accepted epochs, pasting 
-       them one after the other into a single file.

-      

-       Two types of markers are generated:

-	  
    
-		  
  • Markers with names epochXXX, XXX 
-		  being the index of the currrent epoch.
    These markers extend over 
-		  the whole epoch, from beginning to ending.
    • 
-		  
  • Markers with the trigger code of the current 
-		  epoch.
    Their positions are set at the correct trigger origin, after 
-		  the pre-stimulus interval.
    • 
-	  

-	  

-       This is done only once, it does not matter if epochs are Merged
-        or Split.

-      

-       Output File Type

-      

-       Preset list for you to select the file type used for all the output data.

-      

-       Tracks

-      

-        

-      

-       Write in the Ouput Files:

-      

-        

-      

-       the Excluded Channels

-      

-       Select this if the excluded channels 
-       are to be written to the output files anyway. In this way, you can 
-       assure you get the expected number of tracks (though the exluded will 
-       certainly look noisy).

-      

-       the Auxiliary Channels

-      

-       Select this if the auxiliary channels 
-       are to be written to the output files.

-      

-       Options

-      

-        

-      

-       For each Ouput Files:

-      

-        

-      

-       Add a Marker at Epoch Origin

-      

-       To help visualize the epoch origin, 
-       select this to conveniently add a marker on (most of) the outputed files.

-      

-       It does nothing if there are no Pre-Frames,
-        as the first TF is the epoch origin (see length
-        and origin position).

-      

-       See how the epoch origin is rendered in 
-       the EEG display.

-      

-       Open File(s) Upon Completion

-      

-       To automatically open the main resulting files.

-      

-       << Previous  |  Next >>

-      

-       Use these buttons to navigate through the previous and next dialogs 
-       (if any).

-      

-       See which current dialog you are in, and to which other dialogs you 
-       connect, in the tab-like part at the top of the dialog under 
-       the title.

-      

-       These buttons are enabled if the parameters of the current 
-       dialog are OK. If they don't (not enough informations, 
-       inconsistent ones, etc...), or if there is no neighboring dialog to 
-       switch to, some of these buttons are disabled.

-      

-       Process

-      

-       This button actually launches the averaging process.

-      

-       This button remains disabled until all the parameter 
-       dialogs have received enough (and consistent) informations. If 
-       this is not the case, first check the current dialog: if its 
-       "Next" button is disabled, the problem is in the current 
-       dialog. Otherwise, browse the other dialogs for some missing informations.

-      

-       Cancel

-      

-       Quit the dialog (although it will be sad...).

-      

-       Help

-      

-       Launch the Help to the right page (should be here...).

-  

-    

-  

-   Output Files dialog - Technical points & hints

-  

-   Splitting Triggers and Sums: WTF is that 
-   option?

-  

-   This is quite simple, let's have a well designed experiment with 4 
-   triggers, each of them being already something testable (say, a condition).

-  

-   By splitting triggers, you can create 4 different set of files,
-    one set for each trigger. In this set you can choose to put either 
-   the average, the SD, the SE and the sum (of all accepted epochs of a 
-   given trigger type).

-  

-   Now, you can directly compare condition 1 and condition 2, you 
-   are already done with the right files, including the SD / SE.

-  

-   You can also very easily compare conditions 1+2 against conditions 3+4,
-    f.ex.: just add together the Sum files (not the average!) of 
-   conditions 1 and 2, then 3 and 4. Divide the new 1+2 and 3+4 files by 
-   their corresponding number of summed epochs, and there you are with 
-   your averages of conditions 1+2, and 3+4.

-  

-    

-  

-   You can repeat in all the manners you like this joining of splitted 
-   triggers, and never have to do again the whole lengthy and 
-   straining Averaging process.

-  

-   Input and output file types

-  

-   The input and output files need not to be of the same type.

-  

-   Therefore, it's up to you to set the output file type according to 
-   your practical needs. The prefered choice of output is usually the 
-   same as the input one, or .eph or .ep 
-   text files. But you can average .ris binary files and 
-   output .eph text files, or averaging .eph 
-   text files binary files and outputting .ris binary files.

-  

-   If the output file type still does not fit you, you can still convert
-    them.

-  

-    

-  

-   Also note that when averaging Frequency files, the output type is 
-   always .freq.

-  

-   Averaging Control dialog

-  

-   Once all the parameters have been 
-   entered, the control dialog appears. It is updated in real-time 
-   with the current state of the EEG, and waits for some user choice 
-   (see Operating the averaging process):

-  

-   

-  

-   
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-   

-      

-       Averaging Control

-      

-        

-      

-        

-      

-       On top of the window, you find the name of the current file.

-      

-       TRIGGER

-      

-       Informations related to the current trigger.

-      

-       Code

-      

-       The current trigger / marker code.

-      

-       Position in TF

-      

-       The epoch origin of the current 
-       trigger, in time frame.

-      

-       Relative Index

-      

-       Just to indicate the position order of the current trigger.

-      

-       #Acc

-      

-       Number of accepted triggers until now.

-      

-       #Rej

-      

-       Number of rejected triggers until now.

-      

-       Accept Current

-      

-       Accept the current epoch.

-      

-       Reject Current

-      

-       Reject the current epoch.

-      

-       Accept TFs

-      

-       Accept all epochs for the period of 
-       time specified in the edit field below (in TF). Default range is set to 
-	   2s.

-      

-       The time interval starts from the current epoch origin. Forthcoming 
-       epochs are accepted if their origins stand within that interval.

-      

-       Reject TFs

-      

-       Reject all epochs for the period of time specified in the edit field 
-       below (in TF). Default range is set to 2s.

-      

-       The time interval starts from the current epoch origin. Forthcoming 
-       epochs are rejected if their origins stand within that interval.

-      

-       Accept while Ok

-      

-       Accept all the valid epochs,
-        starting from the current one, until it stumbles upon a bad epoch 
-       (if any) and stops there.

-      

-       If the current epoch is a bad one, the button is off.

-      

-       Reject while Bad

-      

-       Reject all the bad epochs, starting from the current one, until
-        it finds a valid epoch (if any) and stops there.

-      

-       If the current epoch is a valid one, the button is off.

-      

-       Accept Cond.

-      

-       This will conditionally accept all the remaining epochs,
-        including the current one.

-      

-       "Conditionally" means that each epoch will be accepted only 
-       if all tests are Ok, and rejected otherwise.

-      

-       When you press this button, it will run until the end of file 
-       (subsequently closing it), so there is no more chance for you to 
-       interact with the control dialog!

-      

-       Undo Last

-      

-       Undo the choice made on the last epoch,
-        which means:

-      
    
-       
  • 
-       
    
-        going back to the previous epoch presented,
    
-        
  • cancelling the choice made by the user (accept or reject),
    
-        
  • and waiting for a new choice.
    
-       

-      

-       By pressing many times this button, you can even rewind to the very 
-       first epoch that was presented to you upon the file opening (only for 
-       the current file, though).

-      

-       Even if the user accepted / rejected a whole bunch of epochs at a 
-       time (Accept / Reject TFs, or Accept
-        / Rreject while...), each single epoch can be individually undone.

-      

-       Accepting, rejecting and undoing any number of times does not alter 
-       the precision of the computations.

-      

-       TRACKS

-      

-       Informations about tracks within the current epoch.

-      

-       Regular

-      

-       If the regular tracks test has 
-       been selected, it shows which one are concerned with the Min and Max 
-       values displayed below.

-      

-       It can either display "ALL", if all the regular tracks are 
-       Ok (below the threshold).

-      

-       Or it can display the list of regular tracks that are off the threshold.

-      

-       Min

-      

-       Min value of all the regular tracks listed in the field above.

-      

-       Max

-      

-       Max value of all the regular tracks listed in the field above.

-      

-       Rejection Threshold

-      

-       For the regular tracks, only.

-      

-       Auxiliaries

-      

-       If the auxiliray tracks test has 
-       been selected, it shows which one are concerned with the Min and Max 
-       values displayed below.

-      

-       It can either display "ALL", if all the regular tracks are 
-       Ok (below the threshold).

-      

-       Or it can display the list of regular tracks that are off the threshold.

-      

-       Min

-      

-       Min value of all the auxiliary tracks listed in the field above.

-      

-       Max

-      

-       Max value of all the auxiliary tracks listed in the field above.

-      

-       Rejection Threshold

-      

-       For the auxiliary tracks, only.

-      

-        

-      

-        

-      

-       Zoom Bad(s)

-      

-       When activated, if the current epoch has some bad channels 
-       (always drawn in magenta), they will be the only one shown on display.
-        Therefore you can have a better view and an easier choice (hopefully).

-      

-       If none of the channels are bad, the button has no effect and all the 
-       non-excluded tracks are shown.

-      

-       You can press anytime on this button to focus or not on the bad 
-       channels. If the button is off, the tracks on display will not 
-       change, whatever if they are bad or not.

-      

-       Exclude Track(s):

-      

-       Press this button to exclude the tracks listed in the edit field 
-       on the right.

-      

-       The edit field is automatically filled with the bad tracks, 
-       the ones that failed the tests (the magenta-colorized
-        tracks on the EEG display).

-      

-       However, you can manually modify this list in the edit field, 
-       removing and / or adding some tracks. Or if the user directly selects
-        / deselects tracks on the EEG display, the list will 
-       be updated accordingly in real-time.

-      

-       The modified list will be the one to be actually excluded.

-      

-       Tracks Excluded:

-      

-       The list of the currently excluded channels.

-      

-        

-      

-        

-      

-       Refresh Cursor

-      

-       During normal operation, the cursor is used to represent the current 
-       epoch. It could happen, though, that its position be modified by the 
-       user. Clicking Refresh Cursor will re-position it correctly.

-      

-       Refresh Tracks

-      

-       During normal operation, the tracks displayed are the one that are 
-       not excluded. But you can still browse your data and change which 
-       tracks are on display. Clicking on Refresh Tracks will bring back the 
-       "good" tracks and remove the "bad" ones.

-      

-       Note that on the next epoch, Cartool will refresh the tracks anyway...

-      

-       If the auxiliaries are not tested, 
-       the user can freely show or hide them. The user's choice will then 
-       remain valid for all epochs.

-      

-       Restart Current

-      

-       Cancel only the current file operations, and restart from the file 
-       beginning. Of course, all the choices made on this file will be lost!

-      

-       This is equivalent to undoing everything.

-      

-       Cancel All

-      

-       Cancel the whole averaging process. No undo, but it will ask 
-       for a confirmation before (see how I care for you?).

-      

-        

-      

-       The progress bar at the bottom indicates the current epoch's position 
-       within the file.

-      

-       It also indicates either "Browsing" if you are currently in 
-       the accept / reject stage, or "Computing" in the 
-       computation stage itself.

-  

-   Monitoring the averaging process

-  
-  

-   

-    

-   

-  
-  

-   Averaging process - Technical points & hints

-  

-   Using .tva files

-  

-   This is a very important and key feature to understand. The tva
-    files allows you to do the following things:

-  
-  

-   Using markers rather than triggers

-  

-   Averaging by using markers instead of 
-   triggers allows you to do any processing you like. Typical uses would be:

-  
-  

-   Be smart, use the keyboard!

-  

-   Most of the parameters and actions in all the dialogs have a keyboard
-    shortcut that highlights when holding the Alt key. 
-   Using the keyboard will save a lot of time and reduce tensions in the 
-   arm and in the hand!

-  

-   Averaging - Results

-  

-   Well, the averaging process can generate quite a lot of files, 
-   so files are named according to the following conventions,
-    and sorted in a hierarchy of directories.

-  

-   This should be quite intuitive to use, but if you need to figure out 
-   all the details, read below:

-  

-    

-  

-   Output files naming convention

-  
-  

-   Output files directories hierarchy

-  
-  

-    

-  

-   See here an example of the directory structure and file naming:

-  

-   

-    
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-    

-       

-        Root directory:

-       

-        

-       

-        Epochs sub-directory:

-       
    
-        
    
-         

-       

-        Trigger 1 sub-directory:

-       
    
-        
    
-         

-   

-  

-    

-  

-   A few more hints about the output files

-  
-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    
+ 
+     

+         

+             Computing ERPs and Averaging Tracks Files
+         

+         

+              
+         

+         

+             What is averaging files?
+         

+         

+             How to run the averaging process
+         

+         
+         

+             Results
+         

+         
+         

+             What is "averaging files"?
+         

+         

+             This is a semi-automated tool to average and / or 
+                 exports
+                 epochs
+              from EEG file(s).
+         

+         

+             The user sets some parameters to control more or less tightly the
+             averaging process, and then has to pilot the averaging
+             (because we want you to have a look to your data!). It is used to
+             compute either ERPs, Grand Means, but also to 
+                 split
+                 a file into epochs
+             .
+         

+         

+             Files that can be processed could be any 
+                 
+                     Spontaneous
+                     EEG
+                 
+              recordings or ERPs,
+             but also Frequency transforms
+             or Results of Inverse Solution.
+         

+         

+             How to run the averaging process
+         

+         

+             Called from the 
+                 
+                     Tools
+                     | Averaging files
+                 
+              menu, there are 
+                 three dialogs for
+                 the parameters
+             . Then, when enough parameters are given and after
+             pressing the Process button, the control dialog appears to
+             monitor the averaging process.
+         

+         

+              
+         

+         
+         

+             Input Files dialog
+         

+         

+             

+                 
+             

+         

+         

+             
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             

+                         

+                             Input Files
+                     

+                         

+                              
+                     

+                         

+                             Input Files
+                     

+                         

+                             A combo-box used to enter 
+                                 which
+                                 files
+                              to average:
+                         

+                         
    
+                             
  • 
+                                 
    
+                                     the edit field (on top) contains the next file to be added
    
+                             
  • 
+                                 the list field (below) contains the 
+                                     files
+                                     already added
+                                 
+         
    
+         

+         

+             Either type or modify the file name in the Edit field, or rather use
+             the Browse button to select a set of files with a file dialog.

+             Then see Add Edit Line from Lists,
+             and Drag & Drop.

+                     

+                         Session
+                 

+                     

+                         Specify an optional session number for the next file to be added. Let
+                         it empty if there are no sessions, or if you don't know (though you should!).

+                         When Cartool will encounter that file, and if it sees something wrong
+                         with the specified session, it will prompt you for the right session.
+                 

+                     

+                         Trigger Validation Files (optional)
+                 

+                     

+                         An optional .tva
+                         file, used to filter out some of the triggers / markers. F.ex.
+                         excluding the false responses from an experiment, or if you
+                         wish to re-do an averaging and to use exactly the same accepted /
+                         rejected triggers.
+                     

+                     

+                         Also available in these files is the Reaction Time, which 
+                             you
+                             can use here
+                          in the averaging.
+                 

+                     

+                         Triggers / Markers
+                 

+                     

+                         The list of triggers / markers
+                         names to be averaged, separated either by a space, a comma or a
+                         semicolumn (but please, just use only one type of separator for the
+                         sake of clarity!), f.ex.:  On Off 1 2 3 4
+                     

+                     

+                         Trigger names that contain a space should be put between double
+                         quotes, f.ex. "eye blink".
+                     

+                     

+                         Wildchars are allowed with the following restrictions:
+                     

+                     
    
+                         
  • 
+                             
    
+                                 Use  *  to specify 
+                                     all
+                                     triggers / markers
+                                 , Cartool will properly expand it with the
+                                 trigger names actually found in each file, one at a time.
    
+                         
  • 
+                             Use  Foo* 
+                             to select all triggers that starts with the letters "Foo"
+                             (case insensitive). F.ex. all correlations between 0.80 to 1.00: Corr8* Corr9* Corr100
    
+                         
  • 
+                             All other uses are not recognized yet (more than
+                             one *, or the * at the beginning).
+                 

+                     

+                         Use Drag & Drop to quickly add files
+                 

+                     

+                         This is only to remind the user of the very convenient 
+                             Drag
+                             & Drop feature
+                         .
+                 

+                     

+                         Add Edit Line from Lists
+                 

+                     

+                         When all the 
+                             edit
+                             fields
+                          have been filled, and in order to validate them, click on
+                         this button to transfer their values into their corresponding list
+                         fields (below).
+                     

+                     

+                         If the Session or Trigger Validation Files edit fields
+                         were left empty, an empty entry is added.

+                         But if the Triggers / Markers edit field is empty, a *
+                         will be added instead, to use all the triggers / markers.
+                     

+                     

+                         After the edit fields have been transfered, they are all cleared for
+                         the next input, except the Triggers / Markers edit field, so
+                         you can re-use the same triggers again.
+                 

+                     

+                         Remove Last Edit Line from Lists
+                 

+                     

+                         Pops the last added line from the lists back to the edit fields,
+                         either to remove the line, or to modify it and insert it again.

+                         By pressing it many times, you also clear out the lists step by step.
+                 

+                     

+                         Replace Current Selected Field
+                 

+                     

+                         First, click on any item in any of the lists (input files, session,
+                         tva, triggers / markers). Its content will appear in its
+                         corresponding edit field (on top) for you to modify it.

+                         Once modified, click on this button to update the originating list
+                         with this very new value, and its done!
+                     

+                     

+                         This is a very practical way to modify the input lists wihtout having
+                         to deconstruct the whole of them (changing only the triggers, the
+                         session, or the files...).
+                 

+                     

+                         Clear All Lists
+                 

+                     

+                         To clear out all the lists at once.
+                 

+                     

+                         Read Lists from File
+                 

+                     

+                         You can directly add a whole set of files to average,
+                         optionally including the session, tva and triggers / markers. Either
+                         you constructed these lists yourself
+                         beforehand, or they were previously 
+                             saved
+                             by Cartool
+                         .
+                     

+                     

+                         Note that the lists are simply augmented, and not replaced. If you
+                         want to do so, clear them out first.

+                         See also Drag & Drop.
+                 

+                     

+                         Write Lists to File
+                 

+                     

+                         You can save the current lists into a
+                         file, in case you want to re-use them.

+                         See the file formats available.
+                 

+                     

+                         Options
+                 

+                     

+                          
+                 

+                     

+                         Types of triggers to consider
+                 

+                     

+                         Cartool currently distinguishes these three types of triggers:
+                     

+                     
+         

+             Here you can select which ones (and only these) you want to use in
+             the averaging.

+             You can also select more than one type, and at least one.
+         

+         

+             Be aware that not selecting a given type (markers f.ex.) will
+             make all of them invisible during the averaging process! This,
+             however, could be very useful, f.ex. if you have duplicate names
+             between triggers and markers and don't want to mix them.

+                     

+                         Electrodes Coordinates file
+                 

+                     

+                         You can optionally specify the 3D 
+                             coordinates
+                             of the electrodes
+                         to see a map
+                         of the current epoch to be averaged.

+                         Also, in this case, a new coordinate file will be outputed with only
+                         the electrodes that will be actually saved in the averaged file
+                         (f.ex. to be used for interpolation
+                         or display of maps).
+                 

+                     

+                         Output Base File Name
+                 

+                     

+                         Specify here a basis for all the file names that will be
+                         generated during the averaging process.
+                     

+                     

+                         Cartool automatically provides you with a smart base file name that
+                         is a compound of the part common to all the files to be averaged
+                         (f.ex. "01conditionthis" and "02conditionthat"
+                         will give "condition"), added with a list of all the
+                         triggers used (f.ex. 1, 2 and 3 will give "123", resulting
+                         to the base file name "condition.123"). Well, it's easier
+                         to see it in action!
+                     

+                     

+                         You can override the base file name, either to simplify it, to fit it
+                         to your own taste, or to avoid overwriting files...
+                 

+                     

+                         << Previous  |  Next >>
+                 

+                     

+                         Use these buttons to navigate through the previous and next dialogs
+                         (if any).
+                     

+                     

+                         See which current dialog you are in, and to which other dialogs you
+                         connect, in the tab-like part at the top of the dialog under
+                         the title.
+                     

+                     

+                         These buttons are enabled if the 
+                             parameters of the current
+                             dialog are OK
+                         . If they don't (not enough informations,
+                         inconsistent ones, etc...), or if there is no neighboring dialog to
+                         switch to, some of these buttons are disabled.
+                 

+                     

+                         Process
+                 

+                     

+                         This button actually launches the averaging process.
+                     

+                     

+                         This button remains 
+                             disabled until all the parameter
+                             dialogs have received enough (and consistent) informations
+                         . If
+                         this is not the case, first check the current dialog: if its
+                         "Next" button is disabled, the problem is in the current
+                         dialog. Otherwise, browse the other dialogs for some missing informations.
+                 

+                     

+                         Cancel
+                 

+                     

+                         Quit the dialog.
+                 

+                     

+                         Help
+                 

+                     

+                         Launch the Help to the right page (should be here...).
+                 

+         

+         

+              
+         

+         

+             Input Files dialog - Technical points & hints
+         

+         

+             File types that can be averaged:
+         

+         
    
+             
  • 
+                 
    
+                     Any EEG files that Cartool recognizes
    
+             
  • Any other ERP files
    
+             
  • 
+                 Frequency files,
+                 in which case the averaging is run one frequency at a time.
    
+             
  • 
+                 Ris files,
+                 results from some Inverse Solution computation
    
+         

+         

+             Pre-filling the Triggers / Markers field
+         

+         

+             Before entering more than one EEG file (by 
+                 Drag
+                 & Drop
+              f.ex.), it can be very convenient to enter the
+             triggers / markers code in the edit field. All subsequent EEG file
+             will inherited these informations. Of course, you can later 
+                 change
+                 / edit all these informations
+             .
+         

+         

+             Sessions
+         

+         

+             There is no problem to use the same file many times in a row, usually
+             if it contains multiple sessions. In this case, specify the session
+             number for each input line.
+         

+         

+             You can Drag & Drop these files
+             directly from the Explorer:
+         

+         
+         

+             File formats to save or retrieve the
+             list of files to average and their parameters:
+         

+         
    
+             
  • 
+                 
    
+                     .csv file
+                     
      
+                         
    • 
+                             First line contains the list of fields that were
+                             saved, separated by a comma or a semicolon, f.ex. "file;session;tva;triggers"
      
+                         
    • 
+                             Next lines contain the actual values, always
+                             separated by a comma or a semicolon, f.ex. "E:\Data\File1.eeg;;;*"
+                 
      
+         
    
+         
  • 
+             
    
+                 .txt text file, with a similar format as the .csv
+                 format above, but separators used are tabs instead of commas
+                 (then rather a .tsv format).
+                 
      
+                     
    • 
+                         First line contains the list of fields that were
+                         saved, separated by a tab, f.ex. "file  
+                         session   tva   triggers"
      
+                     
    • 
+                         Next lines contain the actual values, always
+                         separated by a tab, f.ex.
+                         "E:\Data\File1.eeg         
+                         *"
+             
      
+             
    
+         
  • 
+             
    
+                 In any case, spaces are removed and ignored.
    
+         
  • 
+             The fine point is that you can build the lists
+             yourself, and specify which fields are contained and in 
+                 which
+                 order
+              thanks to the first line format. F.ex.
+             "file;session;tva;triggers", or "triggers;file",
+             or "file". Unknown fields are ignored, and missing fields
+             are applied these rules.
    
+             

+             

+                 Parameters dialog
+             

+             

+                 

+                     
+                 

+             

+             

+                 
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                 

+                             

+                                 Parameters
+                         

+                             

+                                  
+                         

+                             

+                                 Presets:
+                         

+                             

+                                 This is handy to quickly set the main parameters according to the
+                                 most frequent uses, listed in the drop-down box.
+                             

+                             

+                                 The most important parameters will be set, still 
+                                     
+                                         some
+                                         parameters have to be set manually!
+                                     
+                                  And, as usual, double
+                                 check that all your settings make sense...
+                         

+                             

+                                 Retrieve parameters from .vrb file
+                         

+                             

+                                 Give a .vrb file
+                                 generated from a previous averaging process, it will be scanned and
+                                 as much parameters as possible will be retrieved and restored.
+                             

+                             

+                                 This facility will work only with .vrb files compatible
+                                 with this version of Cartool. Anyway, check that the parameters you
+                                 get are the one you expected!
+                             

+                             

+                                 You can also simply Drop the .vrb file into the dialog.
+                         

+                             

+                                 Channel Checking
+                         

+                             

+                                  
+                         

+                             

+                                 Regular channels:
+                         

+                             

+                                 The next parameters concern only the EEG channels.
+                         

+                             

+                                 Test to Threshold Value:
+                         

+                             

+                                 When selected, you have to specify the threshold above which a channel
+                                 will be considered as bad / corrupted.
+                             

+                             

+                                 See channel checking.
+                         

+                             

+                                 Exclude these Channels from Test:
+                         

+                             

+                                 If you already know what channels were noisy or inactive, you can
+                                 fill this field to avoid testing them. Still, you can exclude
+                                 channels later on, during the averaging process.
+                             

+                             

+                                 See channel checking.
+                         

+                             

+                                 Auxiliary channels:
+                         

+                             

+                                 The next parameters concern only the auxiliary channels (ECG, eyes, etc...).
+                         

+                             

+                                 Test to Threshold Value:
+                         

+                             

+                                 When selected, you have to specify the threshold above which an 
+                                     auxiliary
+                                     channel
+                                  will be considered as bad / corrputed.
+                             

+                             

+                                 See channel checking.
+                         

+                             

+                                 Override the Auxiliaries with:
+                         

+                             

+                                 Override the default auxiliary channels.
+                                 The list you provide will completely supersede the default one.
+                         

+                             

+                                 Time Interval
+                         

+                             

+                                  
+                         

+                             

+                                 Epoch Origin:
+                         

+                             

+                                 Choose the time origin of the epochs.
+                                 See length and origin position.
+                         

+                             

+                                 Fixed Time Frame
+                         

+                             

+                                 One and only one TF, at a
+                                 fixed position. Useful for grand averages.
+                         

+                             

+                                 Trigger
+                         

+                             

+                                 The triggers / markers (actually, their onset).
+                         

+                             

+                                 Trigger + Offset
+                         

+                             

+                                 The triggers / markers, plus a given and fixed number of TFs.
+                         

+                             

+                                 Trigger + Reaction Time
+                         

+                             

+                                 The triggers / markers plus a variable step found in the .tva
+                                 file (specified in the files dialog).
+                             

+                             

+                                 Attention: the steps are in milliseconds, not TFs!
+                         

+                             

+                                 Duration
+                         

+                             

+                                 The length of the epoch.
+                         

+                             

+                                 Pre-Frames Duration:
+                         

+                             

+                                 The number of time frames before the origin (positive number,
+                                 or 0). See length and origin position.
+                         

+                             

+                                 Post-Frames Duration:
+                         

+                             

+                                 The number of time frames after the origin (positive number,
+                                 or 0). See length and origin position.
+                         

+                             

+                                 Total Frames Duration:
+                         

+                             

+                                 The total number of time frames. See 
+                                     length
+                                     and origin position
+                                 .
+                             

+                             

+                                 Note that the TF values are also converted into milliseconds if a
+                                 sampling frequency has been found in the files to average.
+                         

+                             

+                                 Computation Parameters
+                         

+                             

+                                 These parameters are applied according to the following sequence.
+                         

+                             

+                                 Data Type:
+                         

+                             

+                                  
+                         

+                             

+                                 Only Positive
+                         

+                             

+                                 Data consist of positive only, scalar data. This could be
+                                 spikes from neuron recordings, or the Results of Inverse Solution, f.ex.
+                             

+                             

+                                 This will logically turn off the Polarity & References options.
+                             

+                             

+                                 See this 
+                                     point on
+                                     positive data
+                                  and also this point.
+                         

+                             

+                                 Signed
+                         

+                             

+                                 Signed scalar values, like, you know, EEG.
+                         

+                             

+                                 Data reference
+                         

+                             

+                                  
+                         

+                             

+                                 No Reference
+                         

+                             

+                                 Data are used as they come from files, no changes occur.
+                         

+                             

+                                 Average Reference
+                         

+                             

+                                 Data are average reference-d, can be
+                                 used for Grand Averages but not necessarily.
+                         

+                             

+                                 Maps / Patterns Polarity:
+                         

+                             

+                                  
+                         

+                             

+                                 Ignore
+                         

+                             

+                                 Polarity of maps does not matter, so ignore it. Inverted maps are
+                                 considered the same (same underlying generators, but with reversed polarity).
+                             

+                             

+                                 Used for spontaneous EEG recordings or 
+                                     FFT
+                                     Approximation
+                                 .
+                         

+                             

+                                 Account
+                         

+                             

+                                 Polarity of maps matter, that is, inverted maps are indeed considered
+                                 as different.
+                             

+                             

+                                 Used for ERPs.
+                         

+                             

+                                 Using Filters:
+                         

+                             

+                                 Clicking on this button brings the usual 
+                                     Filter
+                                     Dialog
+                                 . Fill it according to your needs, and specify a sampling
+                                 frequency if none was found after 
+                                     getting the
+                                     input files
+                                 .
+                             

+                             

+                                 Clicking on the button again turns the filters off.
+                             

+                             

+                                 You can refine on what the filters should be applied to (see
+                                 the possible combinations):
+                         

+                             

+                                 on Results
+                         

+                             

+                                 On the outputted data.
+                         

+                             

+                                 on Display
+                         

+                             

+                                 On the EEG display.
+                         

+                             

+                                 Baseline Correction:
+                         

+                             

+                                 Check this button if you want to apply some baseline correction
+                                 (subtracting each track with its average within a given time period).
+                         

+                             

+                                 Inferior Limit:
+                         

+                             

+                                 Lower boundary as on offset to the epoch origin.
+                             

+                             

+                                 Use negative values before the origin, positive values after.
+                         

+                             

+                                 Superior Limit:
+                         

+                             

+                                 Superior boundary as on offset to the epoch origin.

+                                 Use negative values before the origin, positive values after.
+                             

+                             

+                                 The limits specified need not to be within the range of
+                                 the Pre and Post-Frames. They can be 
+                                     whatever
+                                     you wish
+                                 , Cartool will handle all the cases gracefully.
+                             

+                             

+                                 When changing the "Pre-Frames Duration" value, the
+                                 "Baseline Inferior Limit" will be updated automatically.
+                         

+                             

+                                 Excluding Bad Epochs
+                         

+                             

+                                 Check this button to allow 
+                                     skipping bad
+                                     epochs
+                                 .
+                         

+                             

+                                 at Markers:
+                         

+                             

+                                 Specify the exact marker names of epochs to be skipped.
+                             

+                                 The markers should have been already 
+                                     set
+                                     either manually
+                                 , or by scanning automatically the tracks.
+                             

+                                 Any averaging epoch intersecting
+                                 with any of these bad markers will be automatically
+                                 skipped.
+                         

+                             

+                                 Accepting All Remaining Epochs
+                         

+                             

+                                 Automatically accept all epochs for all files. 
+                                     Any specified thresholding tests will be
+                                     skipped
+                                 .
+                             

+                             

+                                 However, if Excluding Bad Epochs have
+                                 been specified, then it will accept only the non-overlapping epochs only.
+                             

+                             

+                                 This option is however more useful for Grand Averages, where you just
+                                 want to sum files you already know and trust.
+                             

+                             

+                                 Notice that no TVA file will be
+                                 outputted, as for Grand Means we don't care...
+                         

+                             

+                                 << Previous  |  Next >>
+                         

+                             

+                                 Use these buttons to navigate through the previous and next dialogs
+                                 (if any).
+                             

+                             

+                                 See which current dialog you are in, and to which other dialogs you
+                                 connect, in the tab-like part at the top of the dialog under
+                                 the title.
+                             

+                             

+                                 These buttons are enabled if the 
+                                     parameters of the current
+                                     dialog are OK
+                                 . If they don't (not enough informations,
+                                 inconsistent ones, etc...), or if there is no neighboring dialog to
+                                 switch to, some of these buttons are disabled.
+                         

+                             

+                                 Process
+                         

+                             

+                                 This button actually launches the averaging process.
+                             

+                             

+                                 This button remains 
+                                     disabled until all the parameter
+                                     dialogs have received enough (and consistent) informations
+                                 . If
+                                 this is not the case, first check the current dialog: if its
+                                 "Next" button is disabled, the problem is in the current
+                                 dialog. Otherwise, browse the other dialogs for some missing informations.
+                         

+                             

+                                 Cancel
+                         

+                             

+                                 Quit the dialog.
+                         

+                             

+                                 Help
+                         

+                             

+                                 Launch the Help to the right page (should be here...).
+                         

+             

+             

+                  
+             

+             

+                 Parameters dialog - Technical points & hints
+             

+             

+                 Channel checking:
+             

+             
    
+                 
  • 
+                     
    
+                         Within the current epoch, each channel
+                         is tested and if it is above the specified threshold, the channel is
+                         marked as Bad (as well as the whole epoch). Otherwise (below the
+                         threshold), the channel is considered as Ok.
+                     
    
+                 
  • 
+                     
    
+                         If 
+                             both the 
+                                 channel test and the
+                                 auxiliary test
+                             
+                          are selected, then the channels are tested
+                         against the threshold corresponding to which category they belong to
+                         (normal or auxiliary). If any one of the test indicates a channel as
+                         Bad, then the epoch is set as Bad. Conversely, both tests must return
+                         Ok for the epoch to be considered as Ok.
+                     
    
+                 
  • 
+                     
    
+                         If no test at all is active, all epochs will be considered as valid.
+                     
    
+                 
  • 
+                     
    
+                         "Excluded channels"
+                         means excluded from the tests (and from the display BTW).
+                         Whatever their values, excluded channels will not be tested. You can
+                         choose to save or not these channels, according to your needs. And
+                         only if the auxiliaires are being tested can you exclude some of them.
+                     
    
+             

+             
 

+             

+                 The time interval used for testing a given epoch is the
+                 following:
+             

+             
    
+                 
  • 
+                     
    
+                         It is first set to the whole pre- to post-stimulus interval.
+                     
    
+                 
  • 
+                     
    
+                         In case the Baseline extends beyond the pre- and post-stimulus interval,
+                         the tested interval is extended to the 
+                             biggest interval that
+                             encompasses both the baseline and the pre+post interval
+                         .
+                     
    
+                 
  • 
+                     
    
+                         In case of High-Pass filter, it adds 1/6 of the lowest
+                         wave-length on each side of interval. This is to account for slow waves
+                         that could be just below the threshold at the edge of the epoch.
    So
+                         f.ex. with a High-Pass of 1 Hz, the tested interval will be extended by
+                         167ms on the left and on the right.
+                     
    
+             

+             

+                 Overriding the auxiliaries :
+             

+             
+             

+                 Position of the origin, and length of
+                 the output file:
+             

+             
    
+                 
  • 
+                     
    
+                         Consider the case where the epoch
+                         origin is the trigger onset (usual case). Starting with the simple
+                         case where Pre-Frames = 0, and Post-Frames = 250.
+                         Always Total-Frames = Pre + Post = 0 + 250 = 250 time frames in the
+                         output file. Remember that TFs start counting from 0:
+                     
    
+             

+             

+                 

+                     
+                         
+                             
+                             
+                             
+                             
+                             
+                             
+                             
+                             
+                         
+                         
+                             
+                             
+                             
+                             
+                             
+                             
+                             
+                             
+                         
+                         
+                             
+                             
+                             
+                             
+                             
+                             
+                             
+                             
+                         
+                     

+                                 

+                                     

+                                         Epoch origin
+                             

+                                 

+                                     

+                                         Last TF of epoch
+                             

+                                 

+                                     Offset in original file, in TF
+                             

+                                 

+                                     

+                                         0
+                             

+                                 

+                                     

+                                         1
+                             

+                                 

+                                     

+                                         2
+                             

+                                 

+                                     

+                                         . . . . .
+                             

+                                 

+                                     

+                                         247
+                             

+                                 

+                                     

+                                         248
+                             

+                                 

+                                     

+                                         249
+                             

+                                 

+                                     Absolute TF position in output file
+                             

+                                 

+                                     

+                                         0
+                             

+                                 

+                                     

+                                         1
+                             

+                                 

+                                     

+                                         2
+                             

+                                 

+                                     

+                                         . . . . .
+                             

+                                 

+                                     

+                                         247
+                             

+                                 

+                                     

+                                         248
+                             

+                                 

+                                     

+                                         249
+                             

+                 

+             

+             
    
+                 
    
+                     It shows that in the output file, TF 0 is the epoch origin,
+                     and TF 249 is the last time frame (Total-Frames - 1).
+                 
    
+                 
  • 
+                     
    
+                         Now lets have Pre-Frames = 50, Post-Frames = 250, then
+                         Total-Frames = Pre + Post = 50 + 250 = 300 time frames in the output file.
+                     
    
+             

+             

+                 

+                     
+                         
+                             
+                             
+                             
+                             
+                             
+                             
+                             
+                             
+                             
+                             
+                         
+                         
+                             
+                             
+                             
+                             
+                             
+                             
+                             
+                             
+                             
+                             
+                         
+                         
+                             
+                             
+                             
+                             
+                             
+                             
+                             
+                             
+                             
+                             
+                         
+                     

+                                 

+                                     

+                                         First TF of epoch
+                             

+                                 

+                                     

+                                         Epoch origin
+                             

+                                 

+                                     

+                                         Last TF of epoch
+                             

+                                 

+                                     Offset in original file, in TF
+                             

+                                 

+                                     

+                                         -50
+                             

+                                 

+                                     

+                                         -49
+                             

+                                 

+                                     

+                                         ...
+                             

+                                 

+                                     

+                                         -1
+                             

+                                 

+                                     

+                                         0
+                             

+                                 

+                                     

+                                         1
+                             

+                                 

+                                     

+                                         ...
+                             

+                                 

+                                     

+                                         248
+                             

+                                 

+                                     

+                                         249
+                             

+                                 

+                                     Absolute TF position in output file
+                             

+                                 

+                                     

+                                         0
+                             

+                                 

+                                     

+                                         1
+                             

+                                 

+                                     

+                                         ...
+                             

+                                 

+                                     

+                                         49
+                             

+                                 

+                                     

+                                         50
+                             

+                                 

+                                     

+                                         51
+                             

+                                 

+                                     

+                                         ...
+                             

+                                 

+                                     

+                                         298
+                             

+                                 

+                                     

+                                         299
+                             

+                 

+             

+             
    
+                 
    
+                     It shows that in the output file, TFs 0 to 49 are before the trigger,
+                     that TF 50 is the epoch origin, and that 
+                         TF 299 is the
+                         last TF
+                      (corresponding to TF 249 in input file).
+                 
    
+             

+             

+                 Channels filtering:
+             

+             
    
+                 
  • 
+                     
    
+                         Usually, people are filtering the data and want to see the results,
+                         so both Data and Display
+                         should be selected.
+                     
    
+                 
  • 
+                     
    
+                         Filtering the Display but not the Data allows you to visually select
+                         the epochs in a clean display, still
+                         saving the original data (f.ex. preserving all the frequencies).
+                     
    
+                 
  • 
+                     
    
+                         Filtering the Data but not the Display can speed up things a little,
+                         at the risk of confusing you by not understanding why some tracks are
+                         not rejected (because they are actually filtered, and the tests apply
+                         to the filtered values). Not recommended (unless you really trust the program!).
+                     
    
+                 
  • 
+                     
    
+                         To cancel filtering, you can either deselect both the Data and
+                         Display buttons, or open the Filter Dialog
+                         itself and uncheck all filters.
+                     
    
+                 
  • 
+                     
    
+                         You can specify if you want to apply the filters to the 
+                             
+                                 auxiliary
+                                 tracks
+                             
+                          from the Filter dialog.
+                     
    
+             

+             

+                 Ignoring Maps Polarity
+             

+             

+                 For each TF sequentially, take all the maps for all the epochs
+                 and check if they correlate negatively with the 
+                     map with the
+                     highest GFP
+                 . Then invert (multiply by -1) these maps before
+                 proceeding to the next step of the averaging (usually the summation,
+                 saving epoch to file, etc...).
+             

+             

+                 This way, we will sum maps with the same "polarity".
+             

+             

+                 Excluding Bad Epochs
+             

+             
    
+                 
  • 
+                     
    
+                         For each epoch, the pre- and post-stimulus interval is 
+                             inflated by
+                             100 ms
+                          on the left and on the right.
+                     
    
+                 
  • 
+                     
    
+                         Then this interval is tested against each marker which names have been
+                         specified. If any of these marker overlap with the inflated epoch, then it
+                         is rejected.
+                     
    
+                 
  • 
+                     
    
+                         Used in conjunction with the Accepting All Epochs, this would average all
+                         epochs not intersecting the bad markers.
+                     
    
+             

+             

+                 Output Files dialog
+             

+             

+                 

+                     
+                 

+             

+             

+                 
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                 

+                             

+                                 Output Files
+                         

+                             

+                                  
+                         

+                             

+                                 Merging / Splitting Triggers
+                         

+                             

+                                 Choose how to handle the accepted epochs:
+                         

+                             

+                                 According to Trigger Values, accepted epochs are:
+                         

+                             

+                                  
+                         

+                             

+                                 Merged into One File
+                         

+                             

+                                 All epochs are averaged into a single file, whatever their trigger codes.
+                             

+                             

+                                 If there are triggers 1, 2, 3, 4, the result will be a single file
+                                 that sums all these epochs.
+                         

+                             

+                                 Split into Separate Files
+                         

+                             

+                                 
+                                     The epochs are routed to different files
+                                     according to their trigger codes.
+                                 
+                             

+                             

+                                 Epochs from trigger 1 are summed in their own file, and so on with
+                                 epochs from triggers 2, 3 and 4.
+                             

+                             

+                                 The standard error and standard deviation can also be computed on
+                                 these files (if these options are selected, of course).
+                             

+                             

+                                 You can select both the Merge and the Split options.
+                         

+                             

+                                 Data Computed
+                         

+                             

+                                  
+                         

+                             

+                                 Average of Epochs
+                         

+                             

+                                 Compute and save the average of the accepted epochs. This is usually
+                                 what you came for!
+                             

+                             

+                                 Applies both to the Merged and Split files.
+                         

+                             

+                                 Sum of Epochs
+                         

+                             

+                                 Compute and save the sum of the accepted epochs.
+                             

+                             

+                                 Applies both to the Merged and Split files.
+                             

+                             

+                                 Also see this note.
+                         

+                             

+                                 Standard Deviation
+                         

+                             

+                                 Compute and save the standard deviation of the accepted epochs.
+                             

+                             

+                                 Applies both to the Merged and Split files.
+                         

+                             

+                                 Standard Error
+                         

+                             

+                                 Compute and save the standard error of the accepted epochs.
+                             

+                             

+                                 Applies both to the Merged and Split files.
+                         

+                             

+                                 1 File per Epoch
+                         

+                             

+                                 Save the accepted epochs, 
+                                     each epoch
+                                     being put into a separate file
+                                 .
+                             

+                             

+                                 This is done only once, and is not relevant if epochs are 
+                                     Merged
+                                     or Split
+                                 .
+                             

+                                 A single marker is added for each file, with the trigger code
+                                 of the current epoch, at the correct pre-stimulus offset.
+                         

+                             

+                                 All Epochs in 1 File
+                         

+                             

+                                 Save the accepted epochs, 
+                                     pasting
+                                     them one after the other into a single file
+                                 .
+                             

+                             

+                                 Two types of markers are generated:
+                             

+                             
    
+                                 
  • 
+                                     Markers with names epochXXX, XXX
+                                     being the index of the currrent epoch.
    These markers extend over
+                                     the whole epoch, from beginning to ending.
+                                 
    • 
+                                 
  • 
+                                     Markers with the trigger code of the current
+                                     epoch.
    Their positions are set at the correct trigger origin, after
+                                     the pre-stimulus interval.
+                                 
    • 
+                             

+                             

+                                 This is done only once, it does not matter if epochs are 
+                                     Merged
+                                     or Split
+                                 .
+                         

+                             

+                                 Output File Type
+                         

+                             

+                                 Preset list for you to select the file type used for all the output data.
+                         

+                             

+                                 Tracks
+                         

+                             

+                                  
+                         

+                             

+                                 Write in the Ouput Files:
+                         

+                             

+                                  
+                         

+                             

+                                 the Excluded Channels
+                         

+                             

+                                 Select this if the excluded channels
+                                 are to be written to the output files anyway. In this way, you can
+                                 assure you get the expected number of tracks (though the exluded will
+                                 certainly look noisy).
+                         

+                             

+                                 the Auxiliary Channels
+                         

+                             

+                                 Select this if the auxiliary channels
+                                 are to be written to the output files.
+                         

+                             

+                                 Options
+                         

+                             

+                                  
+                         

+                             

+                                 For each Ouput Files:
+                         

+                             

+                                  
+                         

+                             

+                                 Add a Marker at Epoch Origin
+                         

+                             

+                                 To help visualize the epoch origin,
+                                 select this to conveniently add a marker on (most of) the outputed files.
+                             

+                             

+                                 It does nothing if there are no Pre-Frames,
+                                 as the first TF is the epoch origin (see 
+                                     length
+                                     and origin position
+                                 ).
+                             

+                             

+                                 See how the epoch origin is 
+                                     rendered in
+                                     the EEG display
+                                 .
+                         

+                             

+                                 Open File(s) Upon Completion
+                         

+                             

+                                 To automatically open the main resulting files.
+                         

+                             

+                                 << Previous  |  Next >>
+                         

+                             

+                                 Use these buttons to navigate through the previous and next dialogs
+                                 (if any).
+                             

+                             

+                                 See which current dialog you are in, and to which other dialogs you
+                                 connect, in the tab-like part at the top of the dialog under
+                                 the title.
+                             

+                             

+                                 These buttons are enabled if the 
+                                     parameters of the current
+                                     dialog are OK
+                                 . If they don't (not enough informations,
+                                 inconsistent ones, etc...), or if there is no neighboring dialog to
+                                 switch to, some of these buttons are disabled.
+                         

+                             

+                                 Process
+                         

+                             

+                                 This button actually launches the averaging process.
+                             

+                             

+                                 This button remains 
+                                     disabled until all the parameter
+                                     dialogs have received enough (and consistent) informations
+                                 . If
+                                 this is not the case, first check the current dialog: if its
+                                 "Next" button is disabled, the problem is in the current
+                                 dialog. Otherwise, browse the other dialogs for some missing informations.
+                         

+                             

+                                 Cancel
+                         

+                             

+                                 Quit the dialog (although it will be sad...).
+                         

+                             

+                                 Help
+                         

+                             

+                                 Launch the Help to the right page (should be here...).
+                         

+             

+             

+                  
+             

+             

+                 Output Files dialog - Technical points & hints
+             

+             

+                 Splitting Triggers and Sums: WTF is that
+                 option?
+             

+             

+                 This is quite simple, let's have a well designed experiment with 4
+                 triggers, each of them being already something testable (say, a condition).
+             

+             

+                 By splitting triggers, you can create 4 different set of files,
+                 one set for each trigger. In this set you can choose to put either
+                 the average, the SD, the SE and the sum (of all accepted epochs of a
+                 given trigger type).
+             

+             

+                 Now, you can directly compare condition 1 and condition 2, you
+                 are already done with the right files, including the SD / SE.
+             

+             

+                 You can also very easily compare conditions 1+2 against conditions 3+4,
+                 f.ex.: just add together the Sum files (not the average!) of
+                 conditions 1 and 2, then 3 and 4. Divide the new 1+2 and 3+4 files by
+                 their corresponding number of summed epochs, and there you are with
+                 your averages of conditions 1+2, and 3+4.
+             

+             

+                  
+             

+             

+                 You can repeat in all the manners you like this joining of splitted
+                 triggers, and 
+                     never have to do again the whole lengthy and
+                     straining
+                 Averaging process.
+             

+             

+                 Input and output file types
+             

+             

+                 The input and output files need not to be of the same type.
+             

+             

+                 Therefore, it's up to you to set the output file type according to
+                 your practical needs. The prefered choice of output is usually the
+                 same as the input one, or .eph or .ep
+                 text files. But you can average .ris binary files and
+                 output .eph text files, or averaging .eph
+                 text files binary files and outputting .ris binary files.
+             

+             

+                 If the output file type still does not fit you, you can still 
+                     convert
+                     them
+                 .
+             

+             

+                  
+             

+             

+                 Also note that when averaging Frequency files, the output type is
+                 always .freq.
+             

+             

+                 Averaging Control dialog
+             

+             

+                 Once all the parameters have been
+                 entered, the control dialog appears. It is updated in real-time
+                 with the current state of the EEG, and waits for some user choice
+                 (see Operating the averaging process):
+             

+             

+                 
+             

+             

+                 
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 

+                             

+                                 Averaging Control
+                         

+                             

+                                  
+                         

+                             

+                                  
+                         

+                             

+                                 On top of the window, you find the name of the current file.
+                         

+                             

+                                 TRIGGER
+                         

+                             

+                                 Informations related to the current trigger.
+                         

+                             

+                                 Code
+                         

+                             

+                                 The current trigger / marker code.
+                         

+                             

+                                 Position in TF
+                         

+                             

+                                 The epoch origin of the current
+                                 trigger, in time frame.
+                         

+                             

+                                 Relative Index
+                         

+                             

+                                 Just to indicate the position order of the current trigger.
+                         

+                             

+                                 #Acc
+                         

+                             

+                                 Number of accepted triggers until now.
+                         

+                             

+                                 #Rej
+                         

+                             

+                                 Number of rejected triggers until now.
+                         

+                             

+                                 Accept Current
+                         

+                             

+                                 Accept the current epoch.
+                         

+                             

+                                 Reject Current
+                         

+                             

+                                 Reject the current epoch.
+                         

+                             

+                                 Accept TFs
+                         

+                             

+                                 Accept all epochs for the period of
+                                 time specified in the edit field below (in TF). Default range is set to
+                                 2s.
+                             

+                             

+                                 The time interval starts from the current epoch origin. Forthcoming
+                                 epochs are accepted if their origins stand within that interval.
+                         

+                             

+                                 Reject TFs
+                         

+                             

+                                 Reject all epochs for the period of time specified in the edit field
+                                 below (in TF). Default range is set to 2s.
+                             

+                             

+                                 The time interval starts from the current epoch origin. Forthcoming
+                                 epochs are rejected if their origins stand within that interval.
+                         

+                             

+                                 Accept while Ok
+                         

+                             

+                                 Accept all the valid epochs,
+                                 starting from the current one, until it stumbles upon a bad epoch
+                                 (if any) and stops there.
+                             

+                             

+                                 If the current epoch is a bad one, the button is off.
+                         

+                             

+                                 Reject while Bad
+                         

+                             

+                                 Reject all the bad epochs, starting from the current one, 
+                                     until
+                                     it finds a valid epoch
+                                  (if any) and stops there.
+                             

+                             

+                                 If the current epoch is a valid one, the button is off.
+                         

+                             

+                                 Accept Cond.
+                         

+                             

+                                 This will conditionally accept all the remaining epochs,
+                                 including the current one.
+                             

+                             

+                                 "Conditionally" means that each epoch will be accepted only
+                                 if all tests are Ok, and rejected otherwise.
+                             

+                             

+                                 When you press this button, it will run until the end of file
+                                 (subsequently closing it), so there is no more chance for you to
+                                 interact with the control dialog!
+                         

+                             

+                                 Undo Last
+                         

+                             

+                                 Undo the choice made on the last epoch,
+                                 which means:
+                             

+                             
    
+                                 
  • 
+                                     
    
+                                         going back to the previous epoch presented,
    
+                                 
  • cancelling the choice made by the user (accept or reject),
    
+                                 
  • and waiting for a new choice.
+             
    
+             

+             

+                 By pressing many times this button, you can even rewind to the very
+                 first epoch that was presented to you upon the file opening (only for
+                 the current file, though).
+             

+             

+                 Even if the user accepted / rejected a whole bunch of epochs at a
+                 time (Accept / Reject TFs, or 
+                     Accept
+                     / Rreject while
+                 ...), each single epoch can be individually undone.
+             

+             

+                 Accepting, rejecting and undoing any number of times does not alter
+                 the precision of the computations.

+                         

+                             TRACKS
+                     

+                         

+                             Informations about tracks within the current epoch.
+                     

+                         

+                             Regular
+                     

+                         

+                             If the regular tracks test has
+                             been selected, it shows which one are concerned with the Min and Max
+                             values displayed below.
+                         

+                         

+                             It can either display "ALL", if all the regular tracks are
+                             Ok (below the threshold).
+                         

+                         

+                             Or it can display the list of regular tracks that are off the threshold.
+                     

+                         

+                             Min
+                     

+                         

+                             Min value of all the regular tracks listed in the field above.
+                     

+                         

+                             Max
+                     

+                         

+                             Max value of all the regular tracks listed in the field above.
+                     

+                         

+                             Rejection Threshold
+                     

+                         

+                             For the regular tracks, only.
+                     

+                         

+                             Auxiliaries
+                     

+                         

+                             If the auxiliray tracks test has
+                             been selected, it shows which one are concerned with the Min and Max
+                             values displayed below.
+                         

+                         

+                             It can either display "ALL", if all the regular tracks are
+                             Ok (below the threshold).
+                         

+                         

+                             Or it can display the list of regular tracks that are off the threshold.
+                     

+                         

+                             Min
+                     

+                         

+                             Min value of all the auxiliary tracks listed in the field above.
+                     

+                         

+                             Max
+                     

+                         

+                             Max value of all the auxiliary tracks listed in the field above.
+                     

+                         

+                             Rejection Threshold
+                     

+                         

+                             For the auxiliary tracks, only.
+                     

+                         

+                              
+                     

+                         

+                              
+                     

+                         

+                             Zoom Bad(s)
+                     

+                         

+                             When activated, if the current epoch has some bad channels
+                             (always drawn in magenta), they will be the only one shown on display.
+                             Therefore you can have a better view and an easier choice (hopefully).
+                         

+                         

+                             If none of the channels are bad, the button has no effect and all the
+                             non-excluded tracks are shown.
+                         

+                         

+                             You can press anytime on this button to focus or not on the bad
+                             channels. If the button is off, the tracks on display will not
+                             change, whatever if they are bad or not.
+                     

+                         

+                             Exclude Track(s):
+                     

+                         

+                             Press this button to exclude the tracks listed in the edit field
+                             on the right.
+                         

+                         

+                             The edit field is automatically filled with the bad tracks,
+                             the ones that failed the tests (the magenta-colorized
+                             tracks on the EEG display).
+                         

+                         

+                             However, you can manually modify this list in the edit field,
+                             removing and / or adding some tracks. Or if the user directly 
+                                 
+                                     selects
+                                     / deselects tracks
+                                 
+                              on the EEG display, the list will
+                             be updated accordingly in real-time.
+                         

+                         

+                             The modified list will be the one to be actually excluded.
+                     

+                         

+                             Tracks Excluded:
+                     

+                         

+                             The list of the currently excluded channels.
+                     

+                         

+                              
+                     

+                         

+                              
+                     

+                         

+                             Refresh Cursor
+                     

+                         

+                             During normal operation, the cursor is used to represent the current
+                             epoch. It could happen, though, that its position be modified by the
+                             user. Clicking Refresh Cursor will re-position it correctly.
+                     

+                         

+                             Refresh Tracks
+                     

+                         

+                             During normal operation, the tracks displayed are the one that are
+                             not excluded. But you can still browse your data and change which
+                             tracks are on display. Clicking on Refresh Tracks will bring back the
+                             "good" tracks and remove the "bad" ones.
+                         

+                         

+                             Note that on the next epoch, Cartool will refresh the tracks anyway...
+                         

+                         

+                             If the auxiliaries are not tested,
+                             the user can freely show or hide them. The user's choice will then
+                             remain valid for all epochs.
+                     

+                         

+                             Restart Current
+                     

+                         

+                             Cancel only the current file operations, and restart from the file
+                             beginning. Of course, all the choices made on this file will be lost!
+                         

+                         

+                             This is equivalent to undoing everything.
+                     

+                         

+                             Cancel All
+                     

+                         

+                             Cancel the whole averaging process. No undo, but it will ask
+                             for a confirmation before (see how I care for you?).
+                     

+                         

+                              
+                     

+                         

+                             The progress bar at the bottom indicates the current epoch's position
+                             within the file.
+                         

+                         

+                             It also indicates either "Browsing" if you are currently in
+                             the accept / reject stage, or "Computing" in the
+                             computation stage itself.
+                     

+             

+             

+                 Monitoring the averaging process
+             

+             
+             

+                 

+                     
+                 

+             

+             
+             

+                 Averaging process - Technical points & hints
+             

+             

+                 Using .tva files
+             

+             

+                 This is a very important and key feature to understand. The 
+                     tva
+                     files
+                  allows you to do the following things:
+             

+             
    
+                 
  • 
+                     
    
+                         Tva files coming from the stimulation machine will allow you to
+                         automatically reject all epochs where the subject answers were wrong.
+                     
    
+                 
  • 
+                     
    
+                         They will also make possible to compute the epoch 
+                             origin
+                             as the reaction time
+                          from the trigger.
+                     
    
+                 
  • 
+                     
    
+                         Tva files generated by earlier Cartool Averaging Process will allow
+                         you to re-do exactly the same computation (more precisely, to
+                         use exactly the same epochs). Use it if you want to double check your
+                         computations, or if you changed your mind and decided to modify some
+                         parameters and see how the results differ...
+                     
    
+                 
  • 
+                     
    
+                         When Tva files are used, they are first scanned and all the wrong
+                         epochs are labelled as "TVA REJECTED" in the EEG display.
+                     
    
+                 
  • 
+                     
    
+                         The wrong epochs can not be accessed at all, even the Undo procedure
+                         will not work on them. They are definitively discarded.
+                     
    
+             

+             

+                 Using markers rather than triggers
+             

+             

+                 Averaging by using markers instead of
+                 triggers allows you to do any processing you like. Typical uses would be:
+             

+             
+             

+                 Be smart, use the keyboard!
+             

+             

+                 Most of the parameters and actions in all the dialogs have a 
+                     keyboard
+                     shortcut
+                  that highlights when holding the Alt key.
+                 Using the keyboard will save a lot of time and reduce tensions in the
+                 arm and in the hand!
+             

+             

+                 Averaging - Results
+             

+             

+                 Well, the averaging process can generate quite a lot of files,
+                 so files are named according to the following conventions,
+                 and sorted in a hierarchy of directories.
+             

+             

+                 This should be quite intuitive to use, but if you need to figure out
+                 all the details, read below:
+             

+             

+                  
+             

+             

+                 Output files naming convention
+             

+             
    
+                 
  • 
+                     
    
+                         All files will begin with the 
+                             
+                                 Output
+                                 Base File Name
+                             
+                         , f.ex. Base
+                     
    
+                 
  • 
+                     
    
+                         Next, split trigger files (if
+                         any) will contain the name Trigger followed by each of the
+                         actual triggers name, f.ex. Base.Trigger 1
+                     
    
+                 
  • 
+                     
    
+                         Next, summed files (if any)
+                         will contain either one of these names: Sum (number) 
+                         or  SumSqr (number)
+                     
    
+                     
    
+                         The number being the number of epochs actually summed up in the file,
+                         f.ex. Base.Sum (54)  and  Base.Trigger 1.Sum (28)
+                     
    
+                     
    
+                         (the average files themselves don't have anything inserted in this step).
+                     
    
+                 
  • 
+                     
    
+                         Epochs files (if any) will
+                         have the name  Epoch <number>  or  Epochs 
+                         directly inserted following the Base File Name.
+                     
    
+                     
    
+                         F.ex. Base.Epoch 001, Base.Epoch 002, Base.Epoch 003 
+                         or  Base.Epochs
+                     
    
+                 
  • 
+                     
    
+                         Finally, according to which file is outputted, the following file extensions
+                         are appended:
+                     
    
+                     
      
+                         
    • 
+                             
      
+                                 The averaged / summed files
+                                 have the extension specified in the
+                                 parameters:  .ep,
+                                 .eph or .ris
+                             
      
+                             
      
+                                 F.ex. Base.eph,  Base.Sum (54).eph,  
+                                     Base.Epoch
+                                     001.eph
+                                   or  Base.Trigger 1.eph
+                             
      
+                         
    • 
+                             
      
+                                 The verbose file with a summary of all the parameters used
+                                 have the extension: .vrb
+                             
      
+                             
      
+                                 F.ex. Base.eph.vrb
+                             
      
+                         
    • 
+                             
      
+                                 The Trigger Validation with a list of all accepted and
+                                 rejected triggers have the extension: .tva
+                             
      
+                             
      
+                                 F.ex. Base.tva
+                             
      
+                         
    • 
+                             
      
+                                 The (optional) standard deviation / error files have the extensions: .epsd
+                                 or .epse
+                             
      
+                             
      
+                                 F.ex. Base.epse  or  Base.Trigger 1.epse
+                             
      
+                         
    • 
+                             
      
+                                 The (optional) marker files with epoch origin and / or 
+                                     epochs
+                                     beginning
+                                  have extensions: .mrk
+                             
      
+                             
      
+                                 F.ex. Base.eph.mrk,  Base.Sum (54).eph.mrk,  Base.Epochs.eph.mrk 
+                                 or  Base.Trigger 1.eph.mrk
+                             
      
+                     
    
+             

+             

+                 Output files directories hierarchy
+             

+             
    
+                 
  • 
+                     
    
+                         A root directory is created with the 
+                             
+                                 Output
+                                 Base File Name
+                             
+                         , which will hold:
+                     
    
+                     
      
+                         
    • 
+                             
      
+                                 The averaged files
+                             
      
+                         
    • 
+                             
      
+                                 The Trigger Validation files .tva
+                                 (if Accepting All is not selected)
+                             
      
+                         
    • 
+                             
      
+                                 The verbose file .vrb
+                                 are put directly in this root directory.
+                             
      
+                     
    
+                 
  • 
+                     
    
+                         A sub-directory (of the root directory) named  Epochs 
+                         will hold the saved epochs
+                         (if any).
+                     
    
+                 
  • 
+                     
    
+                         A set of sub-directories (of the root directory) named  
+                             Trigger
+                             <trigger name>
+                           will hold the 
+                             
+                                 split
+                                 triggers
+                             
+                          files (if any).
+                     
    
+             

+             

+                  
+             

+             

+                 See here an example of the directory structure and file naming:
+             

+             

+                 

+                     
+                         
+                             
+                             
+                         
+                         
+                             
+                             
+                         
+                         
+                             
+                             
+                         
+                     

+                                 

+                                     Root directory:
+                             

+                                 

+                                     
+                             

+                                 

+                                     Epochs sub-directory:
+                             

+                                 
    
+                                     
    
+                                         
+                             

+                                 

+                                     Trigger 1 sub-directory:
+                             

+                                 
    
+                                     
    
+                                         
+                             

+                 

+             

+             

+                  
+             

+             

+                 A few more hints about the output files
+             

+             
    
+                 
  • 
+                     
    
+                         The verbose file .vrb 
+                             
+                                 is
+                                 a very important one
+                             
+                         , first to know how you computed your
+                         stuff, and secondly to 
+                             automatically
+                             set the averaging parameters
+                         , should you re-do your averaging. 
+                             So
+                             don't lose it!
+                         
+                     
    
+                 
  • 
+                     
    
+                         Both the merged and the split
+                         triggers files will have their own Standard Deviation / Error
+                         (if this was requested in the parameters).
+                     
    
+                 
  • 
+                     
    
+                         When re-doing a computation with a Base File Name previously used, 
+                             all
+                             the old files with be deleted
+                          (without prompting). Sorry about
+                         this "tough love", but it is even more dangerous to let old
+                         and new computation results live together, as you will certainly, and
+                         involuntarily, mix them at some point.
+                     
    
+                     
    
+                         Though, the safety is: Cartool will only erase the files it created,
+                         those who start with the specified Base File Name. If you really
+                         want to keep old stuff, either rename the files you want to keep, or,
+                         even simpler, just use another Base File Name!
+                     
    
+                 
  • 
+                     
    
+                         If you haven't understood yet, choosing a good Base File Name is the
+                         key to clarity and safety for your data: short but meaningful, and
+                         not reusing an old one.
+                     
    
+             

+             

+                  
+             

+             

+                  
+             

+             

+                  
+             

+             

+                  
+             

+             

+                  
+             

+             

+                  
+             

+             

+                  
+             

+             

+                  
+             

+             

+                  
+             

+             

+                  
+             

+             

+                  
+             

+             

+                  
+             

+             

+                  
+             

+             

+                  
+             

+             

+                  
+             

+             

+                  
+             

+             

+                  
+             

+             

+                  
+             

+             

+                  
+             

+             

+                  
+             

+             

+                  
+             

+             

+                  
+             

+             

+                  
+             

+             

+                  
+             

+             

+                  
+             

+             

+                  
+             

+             

+                  
+     

  
 
\ No newline at end of file
diff --git a/docs/ReferenceGuide/computing-inverse-solution-matrices.html b/docs/ReferenceGuide/computing-inverse-solution-matrices.html
index d2000418..9afc4e60 100644
--- a/docs/ReferenceGuide/computing-inverse-solution-matrices.html
+++ b/docs/ReferenceGuide/computing-inverse-solution-matrices.html
@@ -50,2474 +50,3463 @@
 
  
 
- 
-  

-   Creating Inverse Solution Matrices

-  

-    

-  

-   This page is about creating the matrices for solving the 
-   Inverse Solution (IS) problem.

-  

-   You can then use these matrices for display, 
-   or to compute the results of inverse 
-   solutions from EEG (or frequency) files.

-  
Here is a highly recommended article about practical use of the inverse 
-  solutions:

-  
"EEG Source Imaging: A Pratical Review of the Analysis Steps",
+ 
+     

+         

+             Creating Inverse Solution Matrices
+         

+         

+              
+         

+         

+             This page is about creating the matrices for solving the
+             Inverse Solution (IS) problem.
+         

+         

+             You can then use these matrices for display,
+             or to 
+                 
+                     compute the results of inverse
+                     solutions
+                 
+             from EEG (or frequency) files.
+         

+         

+             Here is a highly recommended article about practical use of the inverse
+             solutions:
+         

+         
"EEG Source Imaging: A Pratical Review of the Analysis Steps",
 C.M. Michel, D. Brunet,
 Front. Neurol., 04 April 2019

-  

-   What are Inverse Solution matrices

-   Creating the matrices

-  
-  

-   What are Inverse Solution (IS) matrices

-  

-   These matrices are the solutions of the so-called distributed 
-   linear inverse problem: recovering the most probable sources 
-   of activity from the brain, without any assumption to the number 
-   and/or locations of these sources, given only the EEG surface 
-   recording of these sources.

-  

-   Right away, it should appear that there are quite a lot of 
-   difficulties in this process, some of them being:

-  
    
-   
  • 
-   
    
-    we wish to retrieve 3D activities (inside the brain) from a 2D
-     recording (surface EEG), in which all signals have been summed up;
    
-   
  • 
-   
    
-    the recovered signal is blurred by the underlying tissues 
-    (skull mainly), and weakened proportionally to distance;
    
-   
  • 
-   
    
-    there are many physical constants to account for, not all 
-    being well known (f.ex. skull conductivity);
    
-   
  • 
-   
    
-    there are many mathematical and computational issues in 
-    the process itself.
    
-   

-  

-    

-  

-   But fear not, all these can be reasonably addressed.

-  

-   "The theory"

-  

-   All the theory and formulas will not be covered here but can 
-   be found in the following literature:

-   
-   
+         

+             What are Inverse Solution matrices

+             Creating the matrices
+         

+         
+         

+             What are Inverse Solution (IS) matrices
+         

+         

+             These matrices are the solutions of the so-called 
+                 distributed
+                 linear inverse problem
+             : recovering the 
+                 most probable sources
+                 of activity from the brain
+             , without any assumption to the number
+             and/or locations of these sources, given only the EEG surface
+             recording of these sources.
+         

+         

+             Right away, it should appear that there are quite a lot of
+             difficulties in this process, some of them being:
+         

+         
    
+             
  • 
+                 
    
+                     we wish to retrieve 3D activities (inside the brain) from a 
+                         2D
+                         recording
+                      (surface EEG), in which all signals have been summed up;
+                 
    
+             
  • 
+                 
    
+                     the recovered signal is blurred by the underlying tissues
+                     (skull mainly), and weakened proportionally to distance;
+                 
    
+             
  • 
+                 
    
+                     there are many physical constants to account for, not all
+                     being well known (f.ex. skull conductivity);
+                 
    
+             
  • 
+                 
    
+                     there are many mathematical and computational issues in
+                     the process itself.
+                 
    
+         

+         

+              
+         

+         

+             But fear not, all these can be reasonably addressed.
+         

+         

+             "The theory"
+         

+         

+             All the theory and formulas will not be covered here but can
+             be found in the following literature:
+         

+
+         
 Electrical Neuroimaging,
Chr. Michel, Th. Koenig, D. Brandeis, L.R.R. Gianotti and J. Wackermann,
Cambridge University Press, 2009.
 

 Niedermeyer's Electroencephalography, chapter 55 "EEG Mapping and Source Imaging",
Chr. Michel, B. He,
Lippincott Williams & Wilkins, 2010.
 

 "EEG source imaging",
Chr. Michel, M.M. Murray, G. Lantz, S. Gonzalez, L. Spinelli, R. Grave de Peralta,
Clinical Neurophysiology, 2004.
 

 "Electromagnetic Inverse Solutions in anatomically constrained spherical head models",
L. Spinelli, S. Gonzalez Andino, G. Lantz, Chr. Michel,
Brain Topography, 2000.
 

 "Review of methods for solving the EEG inverse problem",
R.D. Pascual-Marqui,
International Journal of Bioelectromagnetism, 1999.
 

 "Electrical neuroimaging based on biophysical constraints",
R.G. de Peralta Menendez, M.M. Murray, Chr.M. Michel, R. Martuzzi, S.L. Gonzalez Andino,
NeuroImage, 2004

-   
-  
These are also some very interesting reading here about 
-  the forward & inverse model, clinical validation and monkey experiment:

 
-  
+         

+             These are also some very interesting reading here about
+             the forward & inverse model, clinical validation and monkey experiment:
+         

+
+         
 "EEG Source Imaging: A Practical Review of the Analysis Steps",
C.M. Michel, D. Brunet,
Front. Neurol., 04 April 2019 
 

 "Head model and electrical source imaging: A study of 38 epileptic patients",
G. Birot, L. Spinelli, S. Vulliémoz, P. Mégevand, D. Brunet, M. Seeck, C.M. Michel,
NeuroImage: Clinical, 2014 
 

 "Whole-scalp EEG mapping of somatosensory evoked potentials in macaque monkeys",
A.-D. Gindrat, C. Quairiaux, J. Britz, D. Brunet, F. Lanz, C.M. Michel, E.M. Rouiller,
Brain Structure and Function, 2014 
 

 "Spatiotemporal Analysis of Multichannel EEG: CARTOOL",
D. Brunet, M.M. Murray, C.M. Michel,
Computational Intelligence and Neuroscience, 2011

 
-  

-   "The practice"

-  

-   Now that you have read all the above articles ;-) let's go practical.

-  

-   The purpose of these computations is to produce mainly:

-  
    
-   
  • 
-   
    
-    a matrix,
    
-   
  • 
-   
    
-    a set of fixed loci in the brain (called the solution points, 
-    SPs, or solution space).
    
-   

-  

-    

-  

-   The matrix is later multiplied by an EEG column, which gives a column 
-   made of 3D vectors. Each of these 3D vectors is localized 
-   by its corresponding solution point, and is equivalent to a small
-    dipole of any orientation and intensity.

-  

-   Computing the matrix and solution points has to be done only
-    once for a given head and electrodes configuration, which is the 
-   purpose of this section. The last stage of multiplying by some EEG 
-   data is later done either in real-time,
-    through the dedicated RIS toolbox 
-   (highly recommended), or finally to 
-   convert results to volumes.

-  

-   Creating the matrices

-  

-   We can not emphasize enough how sensitive the whole computation is,
-    and that great care should be taken as each of these steps 
-   is a whole process in itself:

-  
    
-   
  1. 
-   
    
-    Preprocessing the MRIs
    
-   
  2. 
-   
    
-    Coregistering the electrodes 
-    on the head
    
-   
  3. 
-   
    
-    Defining the Solution
-     Space
    
-   
  4. 
-   
    
-    Computing the Lead
-     Field (LF):
    
-   
-   
  5. 
-   
    
-    Using the LF to solve the Inverse
-     Problem
    
-   
-   

-  

-    

-  

-   It is suggested to try each of these 5 steps one at a time, 
-   until you get a grasp of each of them. Plus, you can very often re-use
-    the results from a previous run, like re-orientation of the MRIs 
-   or coregistration, that actually has to be done only once...

-  

-    

-  

-   Also see the Drag & Drop 
-   paragraph to learn some handy behaviors to save time (and nerves?).

-  

-    

-  

-   Called from the  Tools
-    | Inverse Solutions | Creating Inverse Solution Matrices  menu, the following dialog holds all the 
-   parameters, organized in 5 (quite) independent parts:

-  

-   

-    

-   

-  

-    

-  

-   
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-       
-     
-     
-       
-       
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-       
-     
-     
-       
-    
-     
-     
-    
-       
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-	   
-     
-     
-       
-	   
-        
-     
-       
-	   
-        
-     
-       
-	   
-     
-     
-       
-	   
-     	  
-     	  
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-       
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-    
-     
-     
-    
-       
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-   

-      

-       (1) MRIs Preprocessing

-       

-      

-       MRIs
-       Presets:

-      

-       Quick setup for the MRIs preprocessing part, then you can tune up the 
-       buttons to your liking.

-      

-       Presets might change according to version, but mainly allow you to 
-	   choose:
    
-		  
  • Real Heads (i.e. subjects or patients) vs
-		  Template Heads (average of multiple subjects)
    • 
-		  
  • Already preprocessed
-		  vs still in need of some tuning
    • 
-	  

-		

-      

-       Full Head MRI:

-      

-       File with the full head, preferably with the following
-        properties.

-      

-       Full Brain MRI:

-      

-       File with the skull-stripped brain, i.e. it should contain the 
-       grey & white matters, and preferably the cerebellum, with the following
-        properties.

-      

-       Grey Mask MRI (optional):

-      

-       Optional file with the Grey Mask.

-       It is recommended to let Cartool compute this mask by letting this 
-	   field empty. The Cartool Grey Mask is much thicker 
-	   than the usual Grey Matter masks given by other packages, and fulfills 
-	   other purposes.

-      

-       Segmented Tissues Head file:

-      

-       Optional, though highly recommend, full head volume segmented 
-	   into tissues. This can really improve on the 
-	   Lead Field computation 
-	   later on.

-      

-       MRIs Preprocessing:

-      

-       Apply any of these steps on the MRIs, with this sequence:

-      
-      

-       Compensates the Bias Field for the brain only, to allow for a 
-       better grey/white matters segmentation.

-      

-       If the bias field has been already corrected for, it doesn't really 
-       hurt to do it again, though it is a useless step.

-      

-       BTW, there is also no need to run the Bias Field correction on templates, 
-	   as it was certainly done at some point during construction.

-      
-      

-       MRI data are noisy, plus the scalp can have creases and ridges due to 
-       lying on the back, or having cushions / earphones / electrodes on the 
-       head. In either cases, we need to smooth out these folds so that the 
-       surface of the head appears more regular:

-      
    
-       
  • 
-       
    
-        Median filter (2.83 voxels diameter, equivalent to 18 neighbors),
    
-       
  • 
-       
    
-        Gaussian filter (6.5 voxels diameter).

-      
-      

-       Re-orient axis to RAS (X:Right, Y:Anterior, Z:Superior),
-        SPM-compatible orientation. We also use the neurological convention, not 
-       the radiological one, that is the right part of the head is seen 
-       the right side.

-      
-      

-       This parameter is highly recommended in case the head is not 
-       perfectly aligned with the Y-Z sagittal plane. It will search for the optimal
-        sagittal plane and reorient the head to fit it into the Y-Z 
-       plane. It needs the full head as input.

-      

-       The search is done with 3 parameters: 1 translation in X 
-       (left-right ), 2 rotations around Y and Z.

-      

-       See here for setting the origin.

-      
-      

-       Note: this step is not longer mandatory, Cartool can do 
-	   without...

-	  

-       Search the brain for the cutting slice with the maximum transverse extent,
-        and reorient the head to fit it into the X-Y plane. This is not 
-       an AC-PC realignment, just a geometrical one. It needs the brain 
-       as input.

-      

-       The search is done with 2 parameters: 1 translation in Z 
-       (vertical ), 1 rotation around X.

-      

-       See here for setting the origin.

-      

-       (2) Electrodes Preprocessing

-       

-      

-       Electrodes
-       Presets:

-      

-       Quick setup for the electrodes preprocessing part.

-	  

-       Current presets are the following:
    
-		  
  • Interactively coregistering the electrodes to the 
-		  full head MRI
    • 
-		  
  • Interactively refining already coregistered 
-		  electrodes
    • 
-		  
  • The coregistration has already been done, just 
-		  load the file - no checks performed!
    • 
-	  

-        

-      

-       Loading Electrodes Coordinates file:

-      

-        File with the electrodes
-        coordinates.

-      

-       (3) Solution Space

-      

-       See: Solution Space and Solution
-        Space vs Lead Field cases

-      

-       Solution Space
-       Presets:

-      

-       Quick setup for the solution space processing part.

-	  

-       Current presets are the following:
    
-		  
  • Computing the solution points, adult case. A 
-		  "low-pass" version of the grey matter will be estimated first, then 
-		  downsampled.
    • 
-		  
  • Computing the solution points, newborn case. This 
-		  will skip differentiating the grey and the white matter and use the 
-		  whole brain.
    • 
-		  
  • Reloading some existing solution points - no checks performed!
    • 
-		  
  • When reloading a full Lead Field (see below), use the solution 
-		  points associated with it
    • 
-	  

-        

-      
Targeted
-        Number of Solution Points:

-      

-       Specify here the desired number of Solution Points,
-        which is actually a sub-sampling of the Grey mask.

-      

-       The actual number will be as close as possible to the user input, but 
-       will certainly slightly differ.

-      

-       See this topic about the number of solution points.

-        

-       This field is also used when reloading a Lead Field, and can be used to 
-	   limit the number of solution points to retain. If not empty, Cartool will 
-	   therefor downsample the solution space 
-       / Lead Field.

-       And BTW, it is much better to interpolate
-        the Lead Field with Cartool own computed Solution Points...
Brain to Grey Mask conversion:You can control how the grey mask will be 
-	 extracted from the brain.

-      This is the default option in Cartool. It extracts 
-	 a kind of band around the grey matter, 
-	 as to make sure the solution space will not have holes in it.

-      Some rare case need to bypass the Regular option 
-	 above, and use the whole brain instead.
These cases are when the Grey 
-	 Matter / White Matter detection fails, as for Babies / Newborns or Monkeys.

-      

-       Loading Solution Points File

-      

-       You can otherwise load an existing Solution Points file. 
-       Either to save time because you have already computed it before, or 
-       to be able to compare results by varying other parameters.

-      

-       Solution Points is a very sensitive topic,
-        be careful not to load erroneous points!

-      

-       (4) Lead Field (Forward Model)

-      

-       See: Lead Field processing 
-       and Solution Space vs 
-       Lead Field cases

-      

-       Lead Field
-       Presets:

-      

-       Quick setup for the Lead Field processing part.

-	  

-       Actual presets might vary on your current version of Cartool, but here are the main 
-	   usual choices:
    
-		  
  • All models currently use the LSMAC (Locally Spherical 
-		  Model with Anatomical Constraints) geometrical transform, 
-		  which in itself is closer to a BEM model than a simple spherical model.
    • 
-		  
  • 3-Shell (scalp, skull, 
-		  CSF + brain) real 
-		  head shape model, with exact analytic equations. 
-		  To be used just for tests.
    • 
-		  
  • 4-Shell (scalp, skull, CSF, brain) real 
-		  head shape model, with exact analytic equations. Recommended model.
    • 
-		  
  • 6-Shell (scalp, 
-		  skull compact, skull spongious, skull compact, CSF, brain) real 
-		  head shape model, with exact analytic equations. Also recommended model.
    • 
-		  
  • 3-Shell (scalp, skull, CSF + brain altogether)
-		  real head shape model, with Ary dipole 
-		  approximation. To be used for backward compatibility only.
    • 
-		  
  • Reloading an existing Lead Field file. Useful to recompute the 
-		  inverse part below, or to test other packages.
    • 
-	  

-		

-      

-       Tissues Boundaries Estimated from:

-      

-       Lead Field computation needs to know, among other things, the 
-	   boundaries between a few tissues:
    
-		  
  • Brain, Skull & Scalp for a 3-Shell model
    • 
-		  
  • + CSF for a 4-Shell model
    • 
-		  
  • +  Skull Spongy and Skull Compact for
-		  6-Shell model
    • 
-	  

-	  

-       These boundaries can currently be retrieved by 2 means.

-		
-		
-      

-       By scanning the input T1 MRIs (head and brain), Cartool can approximate 
-	   the brain, CSF, skull and scalp boundaries. Though no not perfect, 
-	   it is still 
-	   quite robust and accurate enough that it can be used for subjects / patients cases. It also works OK for template.

-		
-		
-      

-       An already full head segmented tissues file can be provided, with each voxels 
-	   labelled as grey matter, white matter, CSF, skull, scalp, and even eyes, 
-	   blood, air etc... This gives the best results, but this labelling should be done ahead of time 
-	   by using another toolbox for 
-	   the time being. For the MNI 2009c asymmetric template, a
-	   segmented tissues volume is available for download.
Targeted age:Mean age for the estimation of skull thickness 
-	 and relative conductivity, in the range [0..100] years.
Setting an age will automatically update 
-	 these two values according to curves estimated from the literature.

-		  
Skull Absolute Conductivity:

-      

-       Absolute conductivity of the skull, in [S/m].

-      	 

-      
Adjusting Skull Mean Thickness:
Mean thickness of the upper part of the skull, 
-	 in [mm].
The automatic skull thickness 
-	 detection actually gives relative thicknesses. They are converted to 
-	 absolute with the help of this value.

Note that this option can be 
-	 independently toggled off, in case user has given a segmented tissues file 
-	 to exactly rely upon.

-      

-       Loading Lead Field

-      

-       Reload a previously computed LF from file.

-      

-       Either to save time to re-compute only the inversion part, or you 
-       might have computed the LF in another toolbox.

-      
-      

-       When loading the Lead Field from file,
-        this is the Lead Field matrix file 
-	   itself.

-      
-      

-       You have to load a Solution Points file 
-       associated with the above loaded Lead Field!

-      

-       (5) Inversion (Inverse Model)

-       

-      

-       Inverse Models:

-      

-       This is where the Lead Field matrix, that computes the voltage received 
-	   at each electrode from the dipoles' currents, is
-	   mathematically
-        "inverted", and will allow us to estimate the 
-	   dipoles' currents from the electrodes voltage (magic!).

-       There are quite a few models available here, all of them being from the
-	   Minimum Norm family.

-       Also note that the inversion part is totally independent
-        from the Lead Field model part!

-      
-      

-       The ancestor of all methods below. The simplest of all.

-      
-      

-       Simple derivation from the MN above.

-      
-      

-       Inspired by the Dale article, kind of similar to dSPM.

-      
-      

-       A standardized MN.

-      
-      

-       Variation to MN with smoothness constraint. The most robust to noise.

-      
-      

-       Sibling to LORETA, with another approach to the smoothness constraint. 
-	   Also robust to noise.

-      
-      

-       Has no errors in localization the max, but only on specific conditions.

-      

-       (Tikhonov Regularization:)

-      

-       Note: previous versions of Cartool used to the 
-	   Tikhonov regularization as an
-	   option. 
-	   But as this option was nearly mandatory, it has been removed from the 
-	   User Interface. The regularization is now systematically computed! 
-	   Plus, the non-regularized matrix is still embedded within the saved 
-	   matrices, should you feel bad about that...

-	  

-       Includes a Tikhonov regularization parameter in the inverse 
-       process. This is highly recommended when dealing with noisy data (so, 
-       all data?).

-      

-       You need not 
-       specify the Tikhonov constant itself, instead a range of 
-       constants will be deduced from the current inverse matrix. You end up 
-       with as many matrices as there are constants, all packed
-        into a super-matrix, from which you could select the best one 
-       according to your data.

-      

-       The actual Tikhonov constants can be found in the verbose
-        file, though (we know you couldn't sleep without knowing them).

-      

-       Options

-      

-        

-      

-       Output Base File Name

-      

-       Base directory and file names for all output files.

-      

-       User annoyance level:

-      

-       How much you want to follow and check each processing step?

-      
    
-       
    
-        Interactive Processing

-      

-       Follow each step of the processing, checking the intermediate results 
-       and answering questions to confirm their validity when needed.

-      

-       If something seems wrong to you, you will usually get kicked out of 
-       the process, and invited by a specific message to check your data.

-      
    
-       
    
-        Batch Processing

-      

-       This will run in a fully automatic mode, without asking any 
-       feedbacks, so that it can be run in the background or in parallel. Check
-        the verbose file and all output files however!

-      

-        

-      

-       Avoid this option

-      
    
-       
  • 
-       
    
-        until you get confident enough into all the steps of the inverse solution,
    
-       
    
-        and
    
-       
  • 
-       
    
-        you absolutely know your data very well (like running again 
-        previously processed data)!
    
-       

-      

-       Otherwise, please refrain from the Black-Box temptation 
-       and don't click on this, do interactively monitor the process!

-      

-        

-      

-       If something seems to fail during the process, usually Cartool will 
-       stop the whole thing, but in some places, it will try to continue anyway.

-  

-   Drag & Dropping files

-  

-   You can Drag & Drop any of the input files into the 
-   dialog, for quicker action. This is usually an un-ambiguous behavior, 
-   f.ex. dropping a .xyz file is only meant to be the electrodes 
-   used for the coregistration.

-  

-    

-  

-   The case worth mentionning now is when dropping some Solution
-    Points files, because they can be either the Solution
-    Points associated with a Lead Field, or the Solution
-    Points for the output Solution Space. Then the following rules 
-   apply that fit most of the cases:

-  

-    

-  
    
-   
  • 
-   
    
-    If a Lead Field is already known (or is also dropped together):
    
-   
-   
  • 
-   
    
-    If no Lead Field is known:
    
-   
      
-    
    • 
-    
      
-     If 2 Solution Points files are dropped
      
-    
-    
    • 
-    
      
-     For any other number of Solution Points files (usually 1), the file 
-     is assigned to the closest field it has been dropped on in the window.
      
-    
    
-   

-  

-   MRIs preprocessing for inverse solutions

-  

-    

-  

-   MRIs input

-  
-  

-   MRIs processing

-  
-  

-   MRIs results

-  
-  

-    

-  

-   MRIs input

-  

-   You need two or three MRI files as input:

-  
    
-   
  • 
-   
    
-    Mandatory, the full head, with as much of the neck / face / jaw as 
-	possible
    
-   
  • 
-   
    
-    Mandatory, the segmented brain:
    
-   
      
-    
    • 
-    
      
-     grey & white matters together;
      
-    
    • 
-    
      
-     but skull-stripped
      
-	   
    • 
-       
      
-       preferably with the cerebellum
      
-    
    
-      
  • 
-	  
    Optionally, you can provide the Grey Mask of your 
-	  liking, although Cartool has its own way to compute it...
    
-   

-  

-    

-  

-   F.ex. a subject's full head, brain and grey mask as computed by Cartool:

-  

-   

-  

-    

-  

-   Note that if you miss the brain MRI part, you can still perform some 
-   very basic transformations, like resizing or re-orienting, but of 
-   course not the whole inverse computation!

-  

-    

-  

-   MRIs properties

-  

-   The input MRIs should fulfill the following conditions:

-  
    
-   
  • 
-   
    
-    Accepted file formats are: Nifti1, 
-	Nifti2 
-	or Analyze.
    
-   
  • 
-   
    
-    They could be either of a template head (MNI f.ex.) or some subject
-     / patient's head.
    
-   
  • 
-   
    
-    The full head should ideally be big enough to include the face
-     & neck, but Cartool could cope with a cropped head at 
-    cerebellum/ear level.
    Also anything other than the head should be 
-	manually deleted, like headphones, tubes, wires etc..
    
-   
  • 
-   
    
-    All MRIs should be T1s, of any size. Anisotropic volumes will 
-	be resliced on the fly.
    
-   
  • 
-   
    
-    All MRIs should share the same orientation, though it 
-    can be of any type.
    
-   
  • 
-   
    
-    MRIs should of course be in a right-hand coordinate system (right 
-    part is seen on the right). This was a problem with the old Analyze format, 
-	but not anymore with Nifti.
    
-   
  • 
-   
    
-    The brain and grey mask MRIs should fit exactly into its 
-	corresponding head (no 
-    tiny shifts, no rotations...).
    
-   
  • 
-   
    
-    Brain should preferably contain the cerebellum.
    
-   

-  

-    

-  

-   If some of these conditions are not fulfilled, you have to somehow 
-   prepare your data before entering this part, either in Cartool 
-   or in some other utilities (MRICro, SPM...).

-  

-    

-  

-   See some good examples of MRIs input:

-  

-   A full MRI that includes the whole face is better, i.e. the 
-   jaw & neck, as it will be easier to coregister the electrodes on it:

-  
    
-   
    
-    
    
-   

-  

-   These MRIs have been cropped at ear level, which is less ideal 
-   but Cartool will try to proceed anyway. Also note that these 2 
-   examples have a different orientation systems, and Cartool 
-   will cope with that, too:

-  
    
-   
    
-    
    
-   

-  

-    

-  

-   See some bad examples of MRIs input:

-  

-   Here are some bad matches between the brain and the full head (slight 
-   lag, and wrong orientation respectively):

-  
    
-   
    
-    
    
-   

-  

-    

-  

-   Here is another problem: headphones were used and are still visible on the 
-   MRI. These for sure will interfere with the head modelling, as if it were 
-   part of the head! So anything "floatting around" the head should be
-   deleted beforehand:

-  

-    

-  

-    

-  

-   MRIs processing

-  

-   We strongly recommend to do as much preprocessing as possible before 
-   entering this toolbox. For example with the 
-   MRI Preprocessing toolbox of 
-   Cartool. However, for cases where this is not possible, you still have a few 
-   of the following options as fallback.

-  

-   Bias Field correction

-  

-   This operation is performed only on the brain MRI.

-  

-   It aims at 
-   reducing a MRI artifact that causes intensities to be slightly 
-   amplified according to position, with a low-frequency type of 
-   pattern. It is a good idea to try to reduce this artifact before 
-   trying to separate the grey matter from the brain!

-  

-   The method used here has been designed specifically for Cartool, and 
-   works by scanning the MRI in many directions, and for each direction 
-   by looking at the distribution of the histogram and applying a 
-   correction along this axis. The artifact is modeled as a 
-   multiplicative factor.

-  

-    

-  

-   See here an example before and after Bias Field correction:

-  

-   

-  

-    

-  

-   Filter noise

-  

-   Two filters are applied internally (you don't see 
-   these), to remove some noise and to smooth out 
-   the ripples from the scalp surface:

-  
    
-   
  • 
-   
    
-    Median filter (2.83 voxels diameter, equivalent to 18 neighbors),
    
-   
  • 
-   
    
-    Gaussian filter (6.5 voxels diameter).
    
-   

-  

-    

-  

-   See here an example of before and after filters, just for the sake of 
-   demonstration, as this is all done internally:

-  
    
-   
    
-    
    
-   

-  

-    

-  

-   Note that these filters are usually not needed with the templates, 
-   as they are already quite noise-free.

-  

-    

-  

-   Realign

-  

-   This includes either 1 to 3 steps:

-  
    
-   
  • 
-   
    
-    Always setting the orientation to the RAS (SPM-compatible 
-	/ default Nifti orientation);
    
-   
  • 
-   
    
-    Optionally aligning the sagittal plane 
-    to the plane that cuts the brain into 2 hemispheres;
    
-   
    
-    and/or
    
-   
  • 
-   
    
-    Optionally aligning the equatorial plane 
-    to the biggest transverse slice of the brain.
    
-   

-  

-    

-  
    
-   
    
-    RAS orientation
    
-   

-  

-   This aims at re-arranging the axis so that:

-  
    
-   
  • 
-   
    
-    X axis points toward the Right side
    
-   
  • 
-   
    
-    Y axis points toward the Anterior side
    
-   
  • 
-   
    
-    Z axis points toward the Superior side
    
-   

-  

-    

-  

-   See an example, going from the PIR (Posterior, Inferior, 
-   Right) orientation to the RAS orientation (look at the color 
-   of the axis, as the labels on the border always indicate the meaning 
-   of the axis, and so won't change!):

-  
    
-   
    
-    -->
    
-   

-  

-    

-  

-   Note that globally, Cartool is quite independent of any orientation 
-   system, but for the sake of simplicity, working here only with the 
-   RAS system makes things much easier and less error prone.

-  

-   There will be some outputs that will go back into your original 
-   MRI size and orientation. That way you can visualize and compare 
-   results with your other modalities.

-  

-    

-  
    
-   
    
-    Sagittal plane
    
-   

-  

-   This is an important step that has to be done at some point 
-   in the MRI processing! We wish to have an as precise as possible 
-   cutting mid-sagittal plane, which will allow us to nicely distribute 
-   solution points "equally" on the left and right cortex. The alternative is 
-   that points would be entangled in a single slice, or mixed between left and 
-   right!

-  

-   This option will find the optimal sagittal plane that cuts the brain into 2 hemispheres,
-    search being done within the full head. The search is done with 3 parameters:
-    1 translation in X (left-right ), 2 rotations around Y and Z.

-  

-    

-  

-   See an example here, with the found sagittal plane superimposed in transparency:

-  
    
-   
    
-    
    
-   

-  

-    

-  

-   Note that this is still an approximation: the 2 hemispheres never 
-   exactly split equally with a simple plane, especially around the visual 
-   cortex.

-  

-    

-  
    
-   
    
-    Transverse plane
    
-   

-  

-   This option will realign the transverse plane in a fashion that closely 
-   resembles to the MNI template. This will bring more consistent and visually 
-   pleasing results.

-  

-   Find the optimal transverse plane, the one that cuts the 
-   brain with the biggest extent (length x width). The search is 
-   done with 2 parameters: 1 translation in Z (vertical ), 1 
-   rotation around X.

-  

-    

-  

-   See an example here, with the found transverse plane superimposed in transparency:

-  
    
-   
    
-    
    
-   

-  

-    

-  

-   Setting the origin

-  

-   This step is not listed in the dialog box, because it is mandatory 
-   and done all the time!

-  

-    

-  

-   We need to set a geometrical center for the brain, the point 
-   from which the brain could best seen as fitting to a sphere (though 
-   we do not explicitly do it). This is because the LSMAC 
-   Lead Field model make use of a spherical model, and therefore 
-   need a reasonable center to compute the relative radii between 
-   solution points and electrodes.

-  

-   In the usual case, the middle of the intersection line of the sagittal
-    plane and equatorial plane is taken:

-  
    
-   
    
-    
    
-   

-  

-    

-  

-   If only the sagittal or the equatorial planes have been 
-   computed, the missing information is used from the center of the 
-   brain's bounding box, and sometimes the origin of the brain, if 
-   it is set.

-  

-   If neither the sagittal nor the equatorial planes have been 
-   computed, the origin is the center of the brain's bounding box,
-    or the origin if it is set.

-  

-    

-  

-   We strongly recommend to always use both 
-   planes detection, except for the MNI template which only needs 
-   the equatorial plane detection!

-  

-    

-  

-   MRIs results

-  

-   We are dealing here with the results of the MRIs
-    preprocessing section only:

-  
    
-   
  • 
-   
    
-    1 to 3 MRIs, depending to your inputs and processing options, saved in
-	Nifti format;
    
-   
      
-    
    • 
-    
      
-     MRI file  basefilename.Head.nii  contains the full head;
      
-    
    • 
-    
      
-     MRI file  basefilename.Brain.nii  contains the full head;
      
-    
    • 
-    
      
-     MRI file  basefilename.Grey.nii  
-     contains the grey mask;
      
-    
    
-   
  • 
-   
    
-    MRIs can be resampled, reoriented, cropped and centered 
-    according to the given parameters;
    
-   
  • 
-   
    
-    These files are written unfiltered (filtering is used only at 
-    processing time).
    
-   

-  

-    

-  

-   See some good examples of MRIs results:

-  

-   Before the Sagittal & Equatorial search, reorientation, 
-   and centering:

-  
    
-   
    
-    
    
-   

-  

-   And after the successful reorientation:

-  
    
-   
    
-    
    
-   

-  

-    

-  

-   See some bad examples of MRIs results:

-  

-   Here the Sagittal and Equatorial searches totally failed (this 
-   is an example, which has been fixed since then):

-  
    
-   
    
-    
    
-   

-  

-   Electrodes preprocessing

-  

-    

-  

-   Electrodes input

-  
-  

-   Electrodes coregistration

-  
-  

-   Electrodes results

-  
-  

-    

-  

-   Electrodes input

-  

-   You need one electrodes
-    file as input:

-  
    
-   
  • 
-   
    
-    The surface electrodes of your recording
    
-	  
  • 
-      
    
-      Any auxiliary / fiducial / funky electrode should be removed 
-	  beforehand!
    
-   

-  

-    

-  

-   Electrodes properties

-  

-   The input electrodes should have the following properties:

-  
    
-   
  • 
-   
    
-    File formats .xyz 
-    or .els.
    
-   
  • 
-   
    
-    Only the surface electrodes should be there, no 
-    auxiliaries, no landmarks etc...
    
-   
  • 
-   
    
-    The electrodes should cover as much surface as possible of the head. 
-	It might be a good idea to work with 257 electrodes f.ex. then remove some 
-	electrodes after the coregistration.
    
-   
  • 
-   
    
-    There should be enough electrodes, at least 64 and above.
    
-   
  • 
-   
    
-    It could be either an electrodes template, or the electrodes 
-    measured from a real head.
    
-   
    
-    In the latter case, the measures should be as accurate as possible,
-     as this has a direct impact on the reliability of the inverse solutions!
    
-   
  • 
-   
    
-    The template should preferably be non-spherical, i.e. it is 
-	far better to have a real head shape.
-	There are work-around, though.
    
-   
  • 
-   
    
-    Input orientation can be arbitrary, and can even be different from 
-    the orientation of the MRIs. This will be reworked during processing.
    
-   

-  

-    

-  

-    

-  

-   See some good examples of electrodes:

-  

-   The first two are electrodes templates with different number of 
-   electrodes, the third one is a subject's real electrodes, all of them 
-   being OK:

-  
    
-   
    
-    
    
-   

-  

-    

-  

-   See some bad examples of electrodes:

-  

-   Not enough electrodes (29!), plus it has a spherical 
-   shape. Don't even think of using this:

-  
    
-   
    
-    
    
-   

-  

-   Globally enough electrodes, but doesn't cover the head enough. 
-   To totally avoid as inverses won't work properly:

-  
    
-   
    
-    
    
-   

-  

-   Enough electrodes, with a good coverage of the head, but has a spherical
-    shape. This is not ideal, though you might be able to proceed
-    through, but still not recommended:

-  
    
-   
    
-    
    
-   

-  

-   Real measured electrodes with heavily corrupted coordinates. Better use a template in this case:

-  
    
-   
    
-    
    
-   

-  

-   This is a good template file, but you need to remove the lone 
-   electrodes / landmarks that "float" below the surface:

-  
    
-   
    
-    
    
-   

-  

-    

-  

-   Electrodes coregistration

-  

-   Here are the available processing on the electrodes set.

-  

-    

-  

-   Doing nothing

-  

-   Don't make use of the electrodes at all, so no Lead Field and 
-   no Inverse Solution either...

-  

-   Note: this is set from Presets list, there is no button for this.

-  

-    

-  

-   Electrodes already coregistered

-  

-   Load and use the electrodes file, which should alreay fit exactly 
-   on the Head MRI: same orientation, centering & scaling.

-  

-   Note: if the MRIs are going through some geometrical transforms 
-   (re-scaling, re-orientation, rotations etc...), then the same 
-   transforms will be applied to the electrodes coordinates, as to 
-   remain correctly coregistered.

-  

-    

-  

-   Interactive coregistration

-  

-   The user has to manually coregister the electrodes set to the 
-   head, in real time. It is his/her responsibility to make sure 
-   the electrodes set is coregistered correctly: positioning the Fpz / 
-   Cz / Oz electrodes, respecting the symmetry on the head etc...

-  

-   It will launch the 
-   Coregistration Toolbox, and resume to the Inverse Matrices 
-   toolbox soon after.

-  

-    

-  

-   Interactively refining an existing coregistration

-  

-   This follows the exact same process as the Interactive
-    coregistration, except that the electrodes model is loaded 
-   as is, without computing a new center, orientation or size. It 
-   assumes the model is already well adjusted to the head 
-   surface, and only needs some slight adjustments.

-  

-    

-  

-   Electrodes results

-  

-   We are dealing here with the results of the Electrodes
-    processing section alone:

-  
    
-   
  • 
-   
    
-    2 electrodes set, saved in .xyz format:
    
-   
      
-    
    • 
-    
      
-     One file  basefilename.xyz  is the one used for the 
-     actual IS computation, which should fit as much as possible the 
-     surface of the head.
      
-    
    • 
-    
      
-     One file  basefilename.For Display.xyz  is a 
-     modified version of the previous one, where the electrodes have been 
-     slightly pushed away from the surface, only to produce a more 
-     visually pleasing display when superimposed to the MRI.
      
-    
      
-     As its name implies, this version is for display use only,
-      and should not be re-used for any computation!
      
-    
    
-   
  • 
-   
    
-    Both sets are coregistered to 
-    the full head MRI;
    
-   

-  

-    

-  

-   See some good examples of 
-   electrodes set results:

-  

-   The result from coregistering a template electrodes set to a real 
-   head, with the results not glued to the surface.

-  

-   First picture is the "official" result, and as it is so 
-   close to the surface, you get this half-blent appearance, which is 
-   normal. Second picture is the same with some depth-shifting 
-   on the electrodes, for a better visual result. Third picture is the For
-    Display version, more appropriate for display use:

-  
    
-   
    
-    
    
-   

-  

-    

-  

-   See some bad examples of electrodes 
-   set results:

-  

-   Here is an example when just loading 
-   an electrodes set and assuming it is coregistered, when indeed 
-   it is not (guess the results won't be that good?):

-  
    
-   
    
-    
    
-   

-  

-    

-  

-   Here is an example where gluing 
-   should have been avoided, the electrodes landing inside the 
-   head through the MRI's defect is not a good thing:

-  
    
-   
    
-    
    
-   

-  

-    

-  

-   Solution Space

-  

-    

-  

-   Grey mask extraction

-  
-  

-   Solution Points computation

-  
-  

-   Loading Solution Points

-   Same Solution Points as Lead Field

-  

-    

-  

-    

-  

-   The solution space is the next thing you need to work on after 
-   the electrodes. It gives the positions of the points where the 
-   inverse solution will be computed.

-  

-   The user can:

-  
-  

-   This, together with the Lead Field options,
-    allows for all possible of combinations.

-  

-    

-  

-   Grey Mask extraction

-  

-   Most of the time, we need a mask of the brain's grey matter:

-  
-  

-    

-  

-   (this step is performed automatically when computing
-    the Solution Points, so there is no explicit option for this in 
-   the dialog)

-  

-    

-  

-   Grey mask processing

-  

-   Cartool processes the brain into a grey mask the following way:

-  
    
-   
  • 
-   
    
-    Correcting for the Bias Field (optionally),
    
-   
  • 
-   
    
-    Estimating the global intensity distributions of the Grey / 
-    White / "Black" matters with a Mixture of Gaussians,
    
-   
  • 
-   
    
-    Classifying each voxel into Grey / White / "Black" 
-    matters by mixing:
    
-   
      
-    
    • 
-    
      
-     Gaussian probabilities based on intensity
      
-    
    • 
-    
      
-     Neighbors likelihood (more grey neighbors -> higher chance 
-     to be grey, too)
      
-    
    
-   
  • 
-   
    
-    Smoothing / filling holes of the resulting grey mask. This step is 
-	quite important before the ensuing downsampling to solution points!
    
-   

-  

-    

-  

-   Note that this conversion can also be ran from the MRI Window, with 
-   the  Filters | Brain 
-   processing | Segment to Grey Matter  menu, and choosing 
-   the Regular or Fat method.

-  

-    

-  

-   See here an example of the grey mask extraction:

-  

-   

-  

-    

-  

-   Grey mask vs Grey matter

-  

-   The grey mask extracted by Cartool is thicker than your 
-   usual grey matter, which can be quite thin near some given 
-   areas of the brain.

-  

-   This is an important point, as smoothing is always required before
-    correctly downsampling to Solution Points. Otherwise we end up 
-   with aliasing effects (Nyquist theorem) of the solution space: 
-   missing points where the spatial frequency is below the downsampling 
-   spatial frequency. So please keep in mind that the grey mask 
-   extraction is more than a grey matter extraction, and is 
-   better done the "Cartool way" to ensure a correct solution space.

-  

-    

-  

-   See here an example of a subject's Grey matter (on the left), and the 
-   corresponding Grey mask from Cartool (on the right):

-  

-   

-  

-    

-  

-   Whole brain as grey mask

-  

-   There are some cases where the usual Grey mask extraction will fail. The most 
-   common cases are when the histograms of the Grey vs White matters are not 
-   correctly estimated: for newborns, or animals like monkeys or mice.

-  

-   In that case, just use the option to compute the grey mask on the whole 
-   brain. It will still poke out the csf parts, but after downsampling you might 
-   get solution points in the Black matter (csf). It doesn't harm the inverse 
-   solution whatsoever, and the inverse shouldn't give you any significatn 
-   results in those points.

-  

-    

-  

-   Here is an example on newborn, first showing the Grey mask, then the brain 
-   with the superimposed solution points:

-  

-   Grey mask on the whole brain of newborn

-  

-    

-  

-    

-  

-   Solution Points computation

-  

-   The Grey mask is basically downsampled 
-   (with great care) into the Solution Points the following way:

-  
    
-   
  • 
-   
    
-    Run a downsampling loop, with a non-integer downsampling factor:
    
-   
      
-    
    • 
-    
      
-     Downsample the grey mask, centered around the geometrical center,
      
-    
    • 
-    
      
-     Remove voxels with less than 8 neighbors out of 26,
      
-    
    • 
-    
      
-     Count remaining voxels,
      
-    
        
-     
      • 
-     
        
-      if close enough to the desired results, exit the downsampling loop,
        
-     
      • 
-     
        
-      otherwise, slightly adjust the downsampling factor and repeat the loop
        
-     
      
-    
    
-   

-  

-    

-  

-    

-  

-   See here an example of a slice of a grey mask, with the corresponding 
-   converted SPs on top:

-  

-   

-  

-    

-  

-    

-  

-   Actually, the Solution Points extraction is an important step 
-   of the Inverse Solutions, very often overlooked, if not totally 
-   ignored in the literature. Here are some points which Cartool is 
-   especially taking care of.

-  

-   SPs Left-right distribution

-  

-   First, remember that the MRIs should have been aligned
-    with their midsagittal plane. That means the geometrical
-    center of the MRIs is going through a YZ plane (the 
-   midsagittal plane) that cuts the brain in two (nearly) equal parts.

-  

-   When downsampling the grey matter into the SPs, the new SPs 
-   downsampled center has to remain through this midsagittal plane.
-    This way will ensure that the resulting SPs distribution will be 
-   optimally distributed across the midsagittal plane, with no side 
-   receiving more SPs than the other one.

-  

-   Otherwise, having an asymmetrical distribution of SPs will have a 
-   dramatic impact on the inverse solutions, with more weights given to 
-   one side of the brain, or even results that could be assigned the wrong
-    side of the brain! Of course, a real asymmetrical 
-   (pathological) brain will have its midsagittal plane set according to 
-   its anatomy, and will have an asymmetrical distribution of 
-   SPs. The point is, the distribution of SPs has to reflect the 
-   reality, and not to artificially favor one side over the other.

-  

-    

-  

-   See here an incorrectly downsampled grey mask (on the left), with too 
-   many SPs on the right side (especially near the midsagittal plane), 
-   and a correct one (on the right), with the little remaining 
-   left-right differences stemming from the actual shape of the brain:

-  

-   

-  

-    

-  

-   SPs Minimum neighborhood

-  

-   The inverse process will later need the computation of a discrete Laplacian 
-   in the Solution Space. To be able to do that correctly, each solution 
-   point has to have enough neighbors. We drew a quite 
-   conservative limit for each Solution Point to have at least 8 
-   neighbors out of 26, and the ones who don't fulfill this 
-   criterion to be removed.

-  

-    

-  

-   SPs Continuity

-  

-   With this method, we aim to have SPs 
-   even in the thinnest parts of the grey matter, and to have an even
-    coverage of the grey matter as a whole. It should be obvious 
-   that there can not be any inverse solution results on non-existent 
-   SPs (!), resulting in a lack of precision for some brain areas.

-  

-   Another risk, if some SPs were to be missing in some grey matter 
-   parts, and some brain activity were to be coming from these very same 
-   areas, would be that the closest SPs to the missing parts 
-   would be ellicited by the inverse solution. But the closest SPs might 
-   prove to be not good enough, like being too far, or being on 
-   the other hemisphere f.ex.

-  

-    

-  

-   See here an example of a bad SPs distribution (on the left), with SPs 
-   missing in the occipital and frontal parts, and a better distribution 
-   (on the right), without holes and with a fuller coverage:

-  

-   

-  

-    

-  

-   Number of SPs

-  

-   Choosing the number of SPs is up to the user, with a recommended 
-   range from 3000 to 6000, and a default set to 6000.

-  

-    

-  

-   There are pros and cons for both low and high number of SPs, some 
-   being more or less obvious:

-  

-   
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-   

-      
    
-       
    
-        Lower number of SPs

-      
    
-       
    
-        Higher number of SPs

-      

-       (+) Faster to compute the matrices

-      

-       (+) Less memory

-      

-       (+) Less numerical precision issues

-      

-       (+) Smaller matrices & Faster display

-      

-       (-) Longer to compute the matrices

-      

-       (-) More memory

-      

-       (-) More numerical precision issues

-      

-       (-) Bigger matrices & Slower display

-      

-       (-) Less spatial resolution

-      

-       (-) Less spatial accuracy

-      

-       (-) Less neighbors around each SPs

-      

-       (+) More spatial resolution

-      

-       (+) Somehow more spatial accuracy

-      

-       (+) More neighbors around each SPs

-  

-    

-  
    
-   
  • 
-   
    
-    Speed is only a slight annoyment. If you are in a hurry for 
-    some reasons, use something like 3000 SPs. Otherwise, run it during a 
-    break, 5000 SPs and 257 electrodes should be done in about 10 minutes 
-    per matrix, 6000 SPs in about 30 minutes.
    
-   
  • 
-   
    
-    Memory issue is a real problem. If you encounter some 
-    problems, make sure your machine has enough of physical memory, is 
-    healthy and set correctly (see Setting
-     your machine correctly). If the problems remain, try to reduce 
-    the number of SPs, from 5000 down to 3000.
    
-   
  • 
-   
    
-    Numerical precision issues come from the fact that inverting 
-    huge matrices will cumulate more errors than for smaller ones. 
-    However, this shouldn't be a real problem here, and nothing can be 
-    really done about that in the realm of digital computers.
    
-   
  • 
-   
    
-    Bigger matrices shouldn't be a real concern with our current 
-    storage capacity. However, a higher number of SPs can be slightly 
-    detrimental to the speed of the inverse display,
-     as there are more rows to compute from the inverse matrix.
    
-   
    
-     
    
-   
    
-    Now, about the sensitive topics of spatial resolution (grid 
-    spacing) and accuracy (to be spot-on). If first recommend you 
-    to get an idea of what
-     these terms really mean.
    
-   
  • 
-   
    
-    More points means more spatial resolution, always,
-     as the resulting grid spacing will be smaller.
    
-   
  • 
-   
    
-    More points also means more accuracy, but up to a limit.
-     First, accuracy can not be better than the resolution. So you have 
-    to increase the number of points to also increase the accuracy. But accuracy
-     will stop improving past a given number of SPs (i.e. the inverse 
-    solution is not "getting better"), somehow due to the fact 
-    that the quantity of information inputted into the system remains the 
-    same, and is set by the number of electrodes. Also, the matrix 
-    inversion process can intrinsically provide only a given level of accuracy.
    
-   
    
-    To summarize, from our experience, the range 3000 to 6000 SPs seems 
-    correct for regular adult human brains.
    
-   
  • 
-   
    
-    As said earlier, there needs to be enough
-     neighbors around each SP. And the more SPs, the more 
-    neighbors there are for each SP. Again, 3000 looks like a minimum 
-    value here.
    
-   

-  

-    

-  

-   SPs Results

-  

-   When computing the Solution Points, you'll have the following results:

-  
-  

-    

-  

-   Some remarks about the output of the Solution Points extraction:

-  
    
-   
  • 
-   
    
-    Points are regularly spaced on a grid, but may not be aligned 
-    on MRI's voxels nor X/Y/Z axis.
    
-   
  • 
-   
    
-    SPs are named according to which octant they belong to:
    
-   
      
-    
    • 
-    
      
-     First, 3 letters within Left/Right, Posterior/Anterior
-      and Inferior/Superior
      
-    
      
-     (like in "LAS" for the Left Anterior Superior),
      
-    
    • 
-    
      
-     Followed by a number within that particular octant
      
-    
      
-     (like in "LAS123" for the 123th point).
      
-    
    
-   

-  

-    

-  

-   See this paragraph about all 
-   combinations of Solution Points / Lead Field options.

-  

-    

-  

-   Loading Solution Points

-  

-   Use this option with care, Cartool will load your file 
-   "as is", so it better had to have these properties:

-  
    
-   
  • 
-   
    
-    It should be in the same space as the MRI Head / Brain / 
-    Electrodes XYZ;
    
-   
  • 
-   
    
-    It should be topologically fit for the inversion
-     step:
    
-   
      
-    
    • 
-    
      
-     Points should be inside  the brain, and preferably in the grey
-      matter (though having points in the white matter is no big 
-     deal). However, points outside the brain will certainly 
-     produce an erroneous Lead Field and inverse matrix.
      
-    
    • 
-    
      
-     Points should be aligned on a grid, but this grid is not 
-     required to be aligned on the X/Y/Z axis, nor to land exactly on the 
-     MRI voxels center.
      
-    
    • 
-    
      
-     Each point should have at least a few neighbors (at least 1!), 
-     to be able to compute some neighborhood constraints, like a Laplacian.
      
-    
    • 
-    
      
-     Left-right distribution should be balanced 
-     and reflect the actual distribution of the grey matter, especially 
-     near the mid-sagittal cutting plane. If the points are not 
-     symetrically distributed, some locations will be missing and the 
-     Laplacian will not be correct, too.
      
-    
    
-   

-  

-    

-  

-   Loading a Solution Points file is of interest if you want to compare 
-   different Lead Fields, while keeping the inverse space constant.

-  

-   Also, see this paragraph about all 
-   combinations of Solution Points / Lead Field options.

-  

-    

-  

-   Here is an example of re-loading a qualified Cartool-computed
-    solution space, on top of the brain:

-  
    
-   
    
-    
    
-   

-  

-    

-  

-   And here is an example of re-loading a Cartool-computed
-    solution space, on top of an existing
-    Lead Field (a typical case for Lead
-    Field interpolation):

-  
    
-   
    
-    
    
-   

-  

-    

-  

-   Same Solution Points as Lead Field

-  

-   If you are reloading a Lead Field, 
-   with its associated Solution Points file,
-    you can simply tell Cartool to use it as the output solution space.

-  

-   In case the amount of Solution Points is too high, you can 
-   (approximately) downsample the solution space and the Lead
-    Field to a given number of points.

-  

-    

-  

-   Also, see this paragraph about all 
-   combinations of Solution Points / Lead Field options.

-  

-    

-  

-   See here an example of (heavy) downsampling, from 150'000 points to 
-   about 3'000:

-  
    
-   
    
-    
    
-   

-  

-    

-  

-   Lead Field processing

-  

-    

-  

-   What is the Lead Field

-   Lead Field input

-   Lead Field computation

-  
-  
-  

-   Loading the Lead Field from file

-  
-  

-   Lead Field results

-  

-    

-  

-   What is the Lead Field (LF)

-  

-   The Lead Field K (sometimes called the Forward Solution 
-   as opposed to the Inverse Solution) is a matrix that embodies 
-   the physical relations that exist between the current 
-   sources in the brain and the electrical potentials on the surface,
-    as picked up by the electrodes. It is made up of:

-  
    
-	  
  •  the geometrical relationship between the solution points 
-	  and the electrodes, i.e. how far and at which angles they lie 
-	  respectively;
    • 
-	  
  • and electromagnetic laws, i.e. how the 
-	  electromagnetic field propagates through different media, and the 
-	  resulting voltage on a receiving electrode.
    • 
-  

-  

-   This matrix is used at the core of the Inverse
-    Solution, and the accuracy of its construction will be directly 
-   reflected in the inverse solutions. See here an example of how one 
-   frontal electrode (yellow) will get most of its potentials from solution points which 
-   dipoles align with the red vectors:

-  

-   

-  

-    

-  

-   There is certainly a trade-off between the complexity 
-   of the model, the amount of parameters to know and adjust, the time 
-   and ease to compute it, and its effectiveness in the 
-   whole Inverse Solutions scheme. For sure, the more realistic and the 
-   more parameters there are, the better the model should be. But there 
-   are also practical issues, like the speed of computation, the reliability of 
-   the results, the real 
-   contribution of a more complex model as compared to a simpler one. Last but 
-   not least, not all physical parameters (like the 
-   skull 
-   conductivity) are well known for the moment.

-  

-    

-  

-   Lead Field input

-  

-   To actually compute the 
-   Lead Field in Cartool, you only need:

-  
-  

-    

-  

-   Or you can otherwise reload 
-   an existing LF, in which case you need:

-  
-  

-    

-  

-   Lead Field computation

-  

-   Computing the Lead Field can be split into a geometrical part, 
-   and an electromagnetic part:

-  
-  

-    

-  

-   You can also visit this paragraph about all 
-   combinations of Solution Points / Lead Field options.

-  

-    

-  

-   LSMAC geometrical model

-  

-   The LSMAC geometrical model is basically a way to transform 
-   the real head shape into some intermediate local spherical model. 
-   Because it is done with different parameters for each electrode position, it 
-   preserves many of the original head properties, like local thicknesses.

-  

-   Also note that this step is totally independent to the electromagnetic model 
-   and its number of layers.

-  

-    

-  

-   Here we can see f.ex. how the spherical parameters will be different for 
-   different 2 electrodes (in yellow):

-  

-   

-  

-    

-  

-   See the article for an introduction to the method:

-    
"Spatiotemporal Analysis of Multichannel EEG: CARTOOL",
Denis Brunet, Micah M. Murray, Christoph M. Michel,
Computational Intelligence and Neuroscience, 2011.

-   The idea is to push the spherical model to the limit of its 
-   capabilities, while keeping the benefits of its equations (relative!) 
-   simplicity. It can be thought of a sort of BEM model, as it 
-   approximates the boundaries of the brain and skull.

-  

-    

-  
    
-   
    
-    LSMAC Spherization step
    
-   

-  

-   The LSMAC processing pipe-line is very similar to the older (and obsolete) SMAC model:

-  

-    

-  

-   MRIs & Electrodes -> Extract Gey mask & Solution Points, 
-   Compute Laplacian -> Compute Scalp / Skull / CSF / Brain radii & Spherical 
-   Model, for each 
-   electrode -> Compute LF

-  

-    

-  

-   It is important to note that a spherical model 
-   is computed underneath each electrode, so the global model accounts 
-   for the real scalp / skull / CSF / brain radii, as a BEM model would.

-  

-    

-  
    
-   
    
-    LSMAC Spherization function
    
-   

-  

-   A global spherization model is computed by fitting a parametric model to the 
-   scalp. It is then used to convert the head to a sphere, with internal skull, 
-   CSF and brain boundaries adjusted for each electrode.

-  

-   See here the spherization sequence done in Cartool, showing: the full 
-   MRI fitted with a scalp model, and how the model warps into a sphere.

-  

-   

-   

-  

-    

-  

-   Tissues boundaries estimated from MRI

-  

-   The electromagnetic models will need 
-   to know the boundaries of either 3 or 4 of the following layers: scalp, 
-   skull, CSF and brain layers. When only 3 layers are actually needed, then the brain and CSF 
-   will be merged into as a single layer with 
-   weighted average conductivity.

-  

-   When this option is checked,
-    Cartool will estimate the radii 
-   of the skull, CSF and brain under each electrode from the provided T1 MRI.

-  

-    

-  

-   Note that in case the skull has been operated and still has some open holes in it, you might 
-   want to switch off this option by using one of the Lead Field Preset. In this case, predefined, 
-   constant radii will be used in the model. Of course, this should be used only 
-   as a last resort...

-  

-    

-  

-   Also note that scanning through a T1 MRI is quite a difficult task, and will 
-   essentially provide relative thicknesses. To recalibrate these 
-   relative thicknesses into absolute thicknesses, Cartool will 
-   use the table shown below.

-  

-    

-  

-   Here is an example of the 4-Shell surfaces extracted from the T1 MRI (left), 
-   and a close-up to 4 electrodes with their corresponding positions shown at 
-   each layer underneath (right):

-  

-   

-  

-   

-  
    
-      
    
-      Skull estimation for each electrode
    
-   

-  

-   For the Lead Field computation, Cartool needs only the skull 
-   information below each electrode locus, and not for the 
-   entire head.

-  

-   To do so, Cartool extracts a radial sample, from the electrode 
-   position to the geometrical center, looks 
-   for a type of valley pattern in the intensity levels near the 
-   expected bone, and takes the edges of this valley as the skull boundaries.

-  

-    

-  

-   See here an example of the relative radii of the inner and outer 
-   parts of the skull, for 257 electrodes, some of which being on the 
-   cheek and near the neck (100% corresponds to the electrode distance):

-  

-   

-  

-   This example shows clearly the advantage of adapting the 
-   scalp/skull/brain radii according to each electrode, as the inner 
-   skull radii vary from 35% to 85%, and the outer part from 42% to 92%.

-  

-    

-  
    
-   
    
-    Layers estimates output
    
-   

-  

-   Some remarks about the output of the Skull estimation:

-  
-  

-   

-  

-   Tissues boundaries computed from 
-   segmented tissues file

-  

-   Better than estimating the boundaries from the T1 
-   MRI, user can provide a volume with each voxel labeled as a given tissue 
-   index.

-  

-    

-  

-   Example of a segmented tissues file (MNI):

-  

-   

-  

-   

-  

-   Tissues indexes are stored in the associated <same file name>.txt file, and is currently 
-   accounting for 14 different tissues:

-  
1 Scalp
+         

+             "The practice"
+         

+         

+             Now that you have read all the above articles ;-) let's go practical.
+         

+         

+             The purpose of these computations is to produce mainly:
+         

+         
    
+             
  • 
+                 
    
+                     a matrix,
+                 
    
+             
  • 
+                 
    
+                     a set of fixed loci in the brain (called the solution points,
+                     SPs, or solution space).
+                 
    
+         

+         

+              
+         

+         

+             The matrix is later multiplied by an EEG column, which gives a column
+             made of 3D vectors. Each of these 3D vectors is localized
+             by its corresponding solution point, and is equivalent to a 
+                 small
+                 dipole
+              of any orientation and intensity.
+         

+         

+             Computing the matrix and solution points has to be done 
+                 only
+                 once
+              for a given head and electrodes configuration, which is the
+             purpose of this section. The last stage of multiplying by some EEG
+             data is later done either in real-time,
+             through the dedicated RIS toolbox
+             (highly recommended), or finally to 
+                 convert results to volumes
+             .
+         

+         

+             Creating the matrices
+         

+         

+             We can not emphasize enough how sensitive the whole computation is,
+             and that great care should be taken as 
+                 each of these steps
+                 is a whole process in itself
+             :
+         

+         
    
+             
  1. 
+                 
    
+                     Preprocessing the MRIs
+                 
    
+             
  2. 
+                 
    
+                     Coregistering the electrodes
+                         on the head
+                     
+                 
    
+             
  3. 
+                 
    
+                     Defining the 
+                         
+                             Solution
+                             Space
+                         
+                     
+                 
    
+             
  4. 
+                 
    
+                     Computing the 
+                         
+                             Lead
+                             Field
+                         
+                      (LF):
+                 
    
+                 
+             
  5. 
+                 
    
+                     Using the LF to solve the 
+                         
+                             Inverse
+                             Problem
+                         
+                     
+                 
    
+                 
+         

+         

+              
+         

+         

+             It is suggested to try each of these 5 steps one at a time,
+             until you get a grasp of each of them. Plus, you can very often 
+                 re-use
+                 the results from a previous run
+             , like re-orientation of the MRIs
+             or coregistration, that actually has to be done only once...
+         

+         

+              
+         

+         

+             Also see the Drag & Drop
+             paragraph to learn some handy behaviors to save time (and nerves?).
+         

+         

+              
+         

+         

+             Called from the  
+                 
+                     Tools
+                     | Inverse Solutions | Creating Inverse Solution Matrices
+                 
+               menu, the following dialog holds all the
+             parameters, organized in 5 (quite) independent parts:
+         

+         

+             

+                 
+             

+         

+         

+              
+         

+         

+             
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+             

+                         

+                             (1) MRIs Preprocessing
+                     

+                          
+                     

+                         

+                             MRIs
+                             Presets:
+                     

+                         

+                             Quick setup for the MRIs preprocessing part, then you can tune up the
+                             buttons to your liking.
+                         

+                         

+                             Presets might change according to version, but mainly allow you to
+                             choose:
    
+                                 
  • 
+                                     Real Heads (i.e. subjects or patients) vs
+                                     Template Heads (average of multiple subjects)
+                                 
    • 
+                                 
  • 
+                                     Already preprocessed
+                                     vs still in need of some tuning
+                                 
    • 
+                             

+                     

+                         

+                             Full Head MRI:
+                     

+                         

+                             File with the full head, preferably with the 
+                                 following
+                                 properties
+                             .
+                     

+                         

+                             Full Brain MRI:
+                     

+                         

+                             File with the skull-stripped brain, i.e. it should contain the
+                             grey & white matters, and preferably the cerebellum, with the 
+                                 following
+                                 properties
+                             .
+                     

+                         

+                             Grey Mask MRI (optional):
+                     

+                         

+                             Optional file with the Grey Mask.
+                         

+                             It is recommended to 
+                                 let Cartool compute this mask by letting this
+                                 field empty
+                             . The Cartool Grey Mask is much thicker
+                             than the usual Grey Matter masks given by other packages, and fulfills
+                             other purposes.
+                     

+                         

+                             Segmented Tissues Head file:
+                     

+                         

+                             Optional, though highly recommend, 
+                                 full head volume segmented
+                                 into tissues
+                             . This can really improve on the 
+                                 Lead Field computation
+                             
+                             later on.
+                     

+                         

+                             MRIs Preprocessing:
+                     

+                         

+                             Apply any of these steps on the MRIs, with this sequence:
+                     

+                         
+                         

+                             Compensates the Bias Field for the brain only, to allow for a
+                             better grey/white matters segmentation.
+                         

+                         

+                             If the bias field has been already corrected for, it doesn't really
+                             hurt to do it again, though it is a useless step.
+                         

+                         

+                             BTW, there is also no need to run the Bias Field correction on templates,
+                             as it was certainly done at some point during construction.
+                     

+                         
+                         

+                             MRI data are noisy, plus the scalp can have creases and ridges due to
+                             lying on the back, or having cushions / earphones / electrodes on the
+                             head. In either cases, we need to smooth out these folds so that the
+                             surface of the head appears more regular:
+                         

+                         
    
+                             
  • 
+                                 
    
+                                     Median filter (2.83 voxels diameter, equivalent to 18 neighbors),
+                                 
    
+                             
  • 
+                                 
    
+                                     Gaussian filter (6.5 voxels diameter).
+                     

+                         
+                         

+                             Re-orient axis to RAS (X:Right, Y:Anterior, Z:Superior),
+                             SPM-compatible orientation. We also use the neurological convention, not
+                             the radiological one, that is the 
+                                 right part of the head is seen
+                                 the right side
+                             .
+                     

+                         
+                         

+                             This parameter is highly recommended in case the head is not
+                             perfectly aligned with the Y-Z sagittal plane. It will search for the 
+                                 optimal
+                                 sagittal plane
+                              and reorient the head to fit it into the Y-Z
+                             plane. It needs the full head as input.
+                         

+                         

+                             The search is done with 3 parameters: 1 translation in X
+                             (left-right ), 2 rotations around Y and Z.
+                         

+                         

+                             See here for setting the origin.
+                     

+                         
+                         

+                             Note: this step is not longer mandatory, Cartool can do
+                             without...
+                         

+                         

+                             Search the brain for the cutting slice with the maximum transverse extent,
+                             and reorient the head to fit it into the X-Y plane. This is not
+                             an AC-PC realignment, just a geometrical one. It needs the brain
+                             as input.
+                         

+                         

+                             The search is done with 2 parameters: 1 translation in Z
+                             (vertical ), 1 rotation around X.
+                         

+                         

+                             See here for setting the origin.
+                     

+                         

+                             (2) Electrodes Preprocessing
+                     

+                          
+                     

+                         

+                             Electrodes
+                             Presets:
+                     

+                         

+                             Quick setup for the electrodes preprocessing part.
+                         

+                         

+                             Current presets are the following:
    
+                                 
  • 
+                                     Interactively coregistering the electrodes to the
+                                     full head MRI
+                                 
    • 
+                                 
  • 
+                                     Interactively refining already coregistered
+                                     electrodes
+                                 
    • 
+                                 
  • 
+                                     The coregistration has already been done, just
+                                     load the file - no checks performed!
+                                 
    • 
+                             

+                     

+                         

+                             Loading Electrodes Coordinates file:
+                     

+                         

+                              File with the 
+                                 electrodes
+                                 coordinates
+                             .
+                     

+                         

+                             (3) Solution Space
+                     

+                         

+                             See: Solution Space and 
+                                 
+                                     Solution
+                                     Space
+                                 vs Lead Field cases
+                             
+                     

+                         

+                             Solution Space
+                             Presets:
+                     

+                         

+                             Quick setup for the solution space processing part.
+                         

+                         

+                             Current presets are the following:
    
+                                 
  • 
+                                     Computing the solution points, adult case. A
+                                     "low-pass" version of the grey matter will be estimated first, then
+                                     downsampled.
+                                 
    • 
+                                 
  • 
+                                     Computing the solution points, newborn case. This
+                                     will skip differentiating the grey and the white matter and use the
+                                     whole brain.
+                                 
    • 
+                                 
  • Reloading some existing solution points - no checks performed!
    • 
+                                 
  • 
+                                     When reloading a full Lead Field (see below), use the solution
+                                     points associated with it
+                                 
    • 
+                             

+                     

+                         

+                             Targeted
+                             Number of Solution Points:
+                     

+                         

+                             Specify here the desired number of Solution Points,
+                             which is actually a sub-sampling of the Grey mask.
+                         

+                         

+                             The actual number will be as close as possible to the user input, but
+                             will certainly slightly differ.
+                         

+                         

+                             See this topic about the number of solution points.
+                         

+                              
+                         

+                             This field is also used when reloading a Lead Field, and can be used to
+                             limit the number of solution points to retain. If not empty, Cartool will
+                             therefor downsample the solution space
+                             / Lead Field.
+                         

+                             And BTW, it is much better to 
+                                 interpolate
+                                 the Lead Field with Cartool own computed Solution Points
+                             ...
+                     
Brain to Grey Mask conversion:
+                         You can control how the grey mask will be
+                         extracted from the brain.
+                     

+                         
+                         This is the default option in Cartool. It extracts
+                         a kind of band around the grey matter,
+                         as to make sure the solution space will not have holes in it.
+                     

+                         
+                         Some rare case need to bypass the Regular option
+                         above, and use the whole brain instead.
These cases are when the Grey
+                         Matter / White Matter detection fails, as for Babies / Newborns or Monkeys.
+                     

+                         

+                             Loading Solution Points File
+                     

+                         

+                             You can otherwise load an existing Solution Points file.
+                             Either to save time because you have already computed it before, or
+                             to be able to compare results by varying other parameters.
+                         

+                         

+                             Solution Points is a very sensitive topic,
+                             be careful not to load erroneous points!
+                     

+                         

+                             (4) Lead Field (Forward Model)
+                     

+                         

+                             See: Lead Field processing
+                             and 
+                                 Solution Space vs
+                                     Lead Field cases
+                                 
+                             
+                     

+                         

+                             Lead Field
+                             Presets:
+                     

+                         

+                             Quick setup for the Lead Field processing part.
+                         

+                         

+                             Actual presets might vary on your current version of Cartool, but here are the main
+                             usual choices:
    
+                                 
  • 
+                                     All models currently use the 
+                                         
+                                             LSMAC (Locally Spherical
+                                             Model with Anatomical Constraints) geometrical transform
+                                         
+                                     ,
+                                     which in itself is closer to a BEM model than a simple spherical model.
+                                 
    • 
+                                 
  • 
+                                     3-Shell (scalp, skull,
+                                     CSF + brain) 
+                                         real
+                                         head shape model
+                                     , with exact analytic equations.
+                                     To be used just for tests.
+                                 
    • 
+                                 
  • 
+                                     4-Shell (scalp, skull, CSF, brain) 
+                                         real
+                                         head shape model
+                                     , with exact analytic equations. Recommended model.
+                                 
    • 
+                                 
  • 
+                                     6-Shell (scalp,
+                                     skull compact, skull spongious, skull compact, CSF, brain) 
+                                         real
+                                         head shape model
+                                     , with exact analytic equations. Also recommended model.
+                                 
    • 
+                                 
  • 
+                                     3-Shell (scalp, skull, CSF + brain altogether)
+                                     real head shape model, with 
+                                         Ary dipole
+                                         approximation.
+                                      To be used for backward compatibility only.
+                                 
    • 
+                                 
  • 
+                                     Reloading an existing Lead Field file. Useful to recompute the
+                                     inverse part below, or to test other packages.
+                                 
    • 
+                             

+                     

+                         

+                             Tissues Boundaries Estimated from:
+                     

+                         

+                             Lead Field computation needs to know, among other things, the 
+                                 boundaries between a few tissues
+                             :
    
+                                 
  • Brain, Skull & Scalp for a 3-Shell model
    • 
+                                 
  • + CSF for a 4-Shell model
    • 
+                                 
  • 
+                                     +  Skull Spongy and Skull Compact for
+                                     6-Shell model
+                                 
    • 
+                             

+                         

+                             These boundaries can currently be retrieved by 2 means.
+                     

+                         
+                     
+                         

+                             By scanning the input T1 MRIs (head and brain), Cartool can 
+                                 approximate
+                                 the brain, CSF, skull and scalp boundaries
+                             . Though no not perfect,
+                             it is still
+                             quite robust and accurate enough that it can be used for subjects / patients cases. It also works OK for template.
+                     

+                         
+                     
+                         

+                             An already full head segmented tissues file can be provided, with each voxels
+                             labelled as grey matter, white matter, CSF, skull, scalp, and even eyes,
+                             blood, air etc... This gives the best results, but this labelling should be done ahead of time
+                             by using another toolbox for
+                             the time being. For the MNI 2009c asymmetric template, a
+                             segmented tissues volume is available for download.
+                     
Targeted age:
+                         Mean age for the estimation of skull thickness
+                         and relative conductivity, in the range [0..100] years.
Setting an age will automatically update
+                         these two values according to curves estimated from the literature.
+                     

+                         
Skull Absolute Conductivity:
+                     

+                         

+                             Absolute conductivity of the skull, in [S/m].
+                         

+                     

+                         
Adjusting Skull Mean Thickness:
+                     

+                         Mean thickness of the upper part of the skull,
+                         in [mm].
The automatic 
+                             skull thickness
+                             detection
+                          actually gives relative thicknesses. They are converted to
+                         absolute with the help of this value.

Note that this option can be
+                         independently toggled off, in case user has given a segmented tissues file
+                         to exactly rely upon.
+                     

+                         

+                             Loading Lead Field
+                     

+                         

+                             Reload a previously computed LF from file.
+                         

+                         

+                             Either to save time to re-compute only the inversion part, or you
+                             might have computed the LF in another toolbox.
+                     

+                         
+                         

+                             When loading the Lead Field from file,
+                             this is the Lead Field matrix file
+                             itself.
+                     

+                         
+                         

+                             You have to load a Solution Points file
+                             associated with the above loaded Lead Field!
+                     

+                         

+                             (5) Inversion (Inverse Model)
+                     

+                          
+                     

+                         

+                             Inverse Models:
+                     

+                         

+                             This is where the Lead Field matrix, that computes the voltage received
+                             at each electrode from the dipoles' currents, is
+                             
+                                 mathematically
+                                 "inverted"
+                             , and will allow us to estimate the
+                             dipoles' currents from the electrodes voltage (magic!).
+                         

+                             There are quite a few models available here, all of them being from the
+                             Minimum Norm family.
+                         

+                             Also note that the inversion part is 
+                                 totally independent
+                                 from the Lead Field model part!
+                             
+                     

+                         
+                         

+                             The ancestor of all methods below. The simplest of all.
+                     

+                         
+                         

+                             Simple derivation from the MN above.
+                     

+                         
+                         

+                             Inspired by the Dale article, kind of similar to dSPM.
+                     

+                         
+                         

+                             A standardized MN.
+                     

+                         
+                         

+                             Variation to MN with smoothness constraint. The most robust to noise.
+                     

+                         
+                         

+                             Sibling to LORETA, with another approach to the smoothness constraint.
+                             Also robust to noise.
+                     

+                         
+                         

+                             Has no errors in localization the max, but only on specific conditions.
+                     

+                         

+                             (Tikhonov Regularization:)
+                     

+                         

+                             Note: previous versions of Cartool used to the 
+                                 Tikhonov regularization
+                              as an
+                             option.
+                             But as this option was nearly mandatory, it has been removed from the
+                             User Interface. The regularization is now systematically computed!
+                             Plus, the non-regularized matrix is still embedded within the saved
+                             matrices, should you feel bad about that...

+                         

+                         

+                             Includes a Tikhonov regularization parameter in the inverse
+                             process. This is highly recommended when dealing with noisy data (so,
+                             all data?).
+                         

+                         

+                             You need not
+                                 specify the Tikhonov constant
+                              itself, instead a range of
+                             constants will be deduced from the current inverse matrix. You end up
+                             with as many matrices as there are constants, all 
+                                 packed
+                                 into a super-matrix
+                             , from which you could select the best one
+                             according to your data.
+                         

+                         

+                             The actual Tikhonov constants can be found in the 
+                                 verbose
+                                 file
+                             , though (we know you couldn't sleep without knowing them).
+                     

+                         

+                             Options
+                     

+                         

+                              
+                     

+                         

+                             Output Base File Name
+                     

+                         

+                             Base directory and file names for all output files.
+                     

+                         

+                             User annoyance level:
+                     

+                         

+                             How much you want to follow and check each processing step?
+                     

+                         
    
+                             
    
+                                 Interactive Processing
+                     

+                         

+                             Follow each step of the processing, checking the intermediate results
+                             and answering questions to confirm their validity when needed.
+                         

+                         

+                             If something seems wrong to you, you will usually get kicked out of
+                             the process, and invited by a specific message to check your data.
+                     

+                         
    
+                             
    
+                                 Batch Processing
+                     

+                         

+                             This will run in a fully automatic mode, without asking any
+                             feedbacks, so that it can be run in the background or in parallel. 
+                                 Check
+                                 the verbose file
+                              and all output files however!
+                         

+                         

+                              
+                         

+                         

+                             Avoid this option
+                         

+                         
    
+                             
  • 
+                                 
    
+                                     until you get confident enough into all the steps of the inverse solution,
+                                 
    
+                                 
    
+                                     and
+                                 
    
+                             
  • 
+                                 
    
+                                     you absolutely know your data very well (like running again
+                                     previously processed data)!
+                                 
    
+                         

+                         

+                             Otherwise, please refrain from the Black-Box temptation
+                             and don't click on this, do interactively monitor the process!
+                         

+                         

+                              
+                         

+                         

+                             If something seems to fail during the process, usually Cartool will
+                             stop the whole thing, but in some places, it will try to continue anyway.
+                     

+         

+         

+             Drag & Dropping files
+         

+         

+             You can Drag & Drop any of the input files into the
+             dialog, for quicker action. This is usually an un-ambiguous behavior,
+             f.ex. dropping a .xyz file is only meant to be the electrodes
+             used for the coregistration.
+         

+         

+              
+         

+         

+             The case worth mentionning now is when dropping some 
+                 
+                     Solution
+                     Points files
+                 
+             , because they can be either the 
+                 Solution
+                 Points associated with a Lead Field
+             , or the 
+                 Solution
+                 Points for the output Solution Space
+             . Then the following rules
+             apply that fit most of the cases:
+         

+         

+              
+         

+         
    
+             
  • 
+                 
    
+                     If a Lead Field is already known (or is also dropped together):
+                 
    
+                 
+             
  • 
+                 
    
+                     If no Lead Field is known:
+                 
    
+                 
      
+                     
    • 
+                         
      
+                             If 2 Solution Points files are dropped
+                         
      
+                         
+                     
    • 
+                         
      
+                             For any other number of Solution Points files (usually 1), the file
+                             is assigned to the closest field it has been dropped on in the window.
+                         
      
+                 
    
+         

+         

+             MRIs preprocessing for inverse solutions
+         

+         

+              
+         

+         

+             MRIs input
+         

+         
+         

+             MRIs processing
+         

+         
+         

+             MRIs results
+         

+         
+         

+              
+         

+         

+             MRIs input
+         

+         

+             You need two or three MRI files as input:
+         

+         
    
+             
  • 
+                 
    
+                     Mandatory, the full head, with as much of the neck / face / jaw as
+                     possible
+                 
    
+             
  • 
+                 
    
+                     Mandatory, the segmented brain:
+                 
    
+                 
      
+                     
    • 
+                         
      
+                             grey & white matters together;
+                         
      
+                     
    • 
+                         
      
+                             but skull-stripped
+                         
      
+                     
    • 
+                         
      
+                             preferably with the cerebellum
+                         
      
+                 
    
+             
  • 
+                 
    
+                     Optionally, you can provide the Grey Mask of your
+                     liking, although Cartool has its own way to compute it...
+                 
    
+         

+         

+              
+         

+         

+             F.ex. a subject's full head, brain and grey mask as computed by Cartool:
+         

+         

+             
+         

+         

+              
+         

+         

+             Note that if you miss the brain MRI part, you can still perform some
+             very basic transformations, like resizing or re-orienting, but of
+             course not the whole inverse computation!
+         

+         

+              
+         

+         

+             MRIs properties
+         

+         

+             The input MRIs should fulfill the following conditions:
+         

+         
    
+             
  • 
+                 
    
+                     Accepted file formats are: 
+                         Nifti1,
+                         Nifti2
+                         or Analyze
+                     .
+                 
    
+             
  • 
+                 
    
+                     They could be either of a template head (MNI f.ex.) or some 
+                         subject
+                         / patient's head
+                     .
+                 
    
+             
  • 
+                 
    
+                     The full head should ideally be big enough to include the 
+                         face
+                         & neck
+                     , but Cartool could cope with a cropped head at
+                     cerebellum/ear level.
    Also 
+                         anything other than the head should be
+                         manually deleted
+                     , like headphones, tubes, wires etc..
+                 
    
+             
  • 
+                 
    
+                     All MRIs should be T1s, of any size. Anisotropic volumes will
+                     be resliced on the fly.
+                 
    
+             
  • 
+                 
    
+                     All MRIs should share the same orientation, though it
+                     can be of any type.
+                 
    
+             
  • 
+                 
    
+                     MRIs should of course be in a right-hand coordinate system (right
+                     part is seen on the right). This was a problem with the old Analyze format,
+                     but not anymore with Nifti.
+                 
    
+             
  • 
+                 
    
+                     The brain and grey mask MRIs should fit exactly into its
+                     corresponding head (no
+                     tiny shifts, no rotations...).
+                 
    
+             
  • 
+                 
    
+                     Brain should preferably contain the cerebellum.
+                 
    
+         

+         

+              
+         

+         

+             If some of these conditions are not fulfilled, you have to somehow
+             prepare your data before entering this part, either in Cartool
+             or in some other utilities (MRICro, SPM...).
+         

+         

+              
+         

+         

+             See some good examples of MRIs input:
+         

+         

+             A full MRI that includes the whole face is better, i.e. the
+             jaw & neck, as it will be easier to coregister the electrodes on it:
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+             These MRIs have been cropped at ear level, which is less ideal
+             but Cartool will try to proceed anyway. Also note that these 2
+             examples have a different orientation systems, and Cartool
+             will cope with that, too:
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+              
+         

+         

+             See some bad examples of MRIs input:
+         

+         

+             Here are some bad matches between the brain and the full head (slight
+             lag, and wrong orientation respectively):
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+              
+         

+         

+             Here is another problem: headphones were used and are still visible on the
+             MRI. These for sure will interfere with the head modelling, as if it were
+             part of the head! 
+                 So anything "floatting around" the head should be
+                 deleted beforehand
+             :
+         

+         

+              
+         

+         

+              
+         

+         

+             MRIs processing
+         

+         

+             We strongly recommend to 
+                 do as much preprocessing as possible before
+                 entering this toolbox
+             . For example with the 
+                 MRI Preprocessing toolbox
+              of
+             Cartool. However, for cases where this is not possible, you still have a few
+             of the following options as fallback.
+         

+         

+             Bias Field correction
+         

+         

+             This operation is performed only on the brain MRI.
+         

+         

+             It aims at
+             reducing a MRI artifact that causes intensities to be 
+                 slightly
+                 amplified according to position
+             , with a low-frequency type of
+             pattern. It is a good idea to try to reduce this artifact before
+             trying to separate the grey matter from the brain!
+         

+         

+             The method used here has been designed specifically for Cartool, and
+             works by scanning the MRI in many directions, and for each direction
+             by looking at the distribution of the histogram and applying a
+             correction along this axis. The artifact is modeled as a
+             multiplicative factor.
+         

+         

+              
+         

+         

+             See here an example before and after Bias Field correction:
+         

+         

+             
+         

+         

+              
+         

+         

+             Filter noise
+         

+         

+             Two filters are applied internally (you don't see
+             these), to remove some noise and to smooth out
+             the ripples from the scalp surface:
+         

+         
    
+             
  • 
+                 
    
+                     Median filter (2.83 voxels diameter, equivalent to 18 neighbors),
+                 
    
+             
  • 
+                 
    
+                     Gaussian filter (6.5 voxels diameter).
+                 
    
+         

+         

+              
+         

+         

+             See here an example of before and after filters, just for the sake of
+             demonstration, as this is all done internally:
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+              
+         

+         

+             Note that these filters are usually not needed with the templates,
+             as they are already quite noise-free.
+         

+         

+              
+         

+         

+             Realign
+         

+         

+             This includes either 1 to 3 steps:
+         

+         
    
+             
  • 
+                 
    
+                     Always setting the orientation to the RAS (SPM-compatible
+                     / default Nifti orientation);
+                 
    
+             
  • 
+                 
    
+                     Optionally aligning the sagittal plane
+                     to the plane that cuts the brain into 2 hemispheres;
+                 
    
+                 
    
+                     and/or
+                 
    
+             
  • 
+                 
    
+                     Optionally aligning the equatorial plane
+                     to the biggest transverse slice of the brain.
+                 
    
+         

+         

+              
+         

+         
    
+             
    
+                 RAS orientation
+             
    
+         

+         

+             This aims at re-arranging the axis so that:
+         

+         
    
+             
  • 
+                 
    
+                     X axis points toward the Right side
+                 
    
+             
  • 
+                 
    
+                     Y axis points toward the Anterior side
+                 
    
+             
  • 
+                 
    
+                     Z axis points toward the Superior side
+                 
    
+         

+         

+              
+         

+         

+             See an example, going from the PIR (Posterior, Inferior,
+             Right) orientation to the RAS orientation (look at the color
+             of the axis, as the labels on the border always indicate the meaning
+             of the axis, and so won't change!):
+         

+         
    
+             
    
+                 -->
+             
    
+         

+         

+              
+         

+         

+             Note that globally, Cartool is quite independent of any orientation
+             system, but for the sake of simplicity, working here only with the
+             RAS system makes things much easier and less error prone.
+         

+         

+             There will be some outputs that will go 
+                 back into your original
+                 MRI size and orientation
+             . That way you can visualize and compare
+             results with your other modalities.
+         

+         

+              
+         

+         
    
+             
    
+                 Sagittal plane
+             
    
+         

+         

+             This is an important step that has to be done at some point
+             in the MRI processing! We wish to have an 
+                 as precise as possible
+                 cutting mid-sagittal plane
+             , which will allow us to nicely distribute
+             solution points "equally" on the left and right cortex. The alternative is
+             that points would be entangled in a single slice, or mixed between left and
+             right!
+         

+         

+             This option will find the optimal sagittal plane that cuts the brain into 2 hemispheres,
+             search being done within the full head. The search is done with 3 parameters:
+             1 translation in X (left-right ), 2 rotations around Y and Z.
+         

+         

+              
+         

+         

+             See an example here, with the found sagittal plane superimposed in transparency:
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+              
+         

+         

+             Note that this is still an approximation: the 2 hemispheres never
+             exactly split equally with a simple plane, especially around the visual
+             cortex.
+         

+         

+              
+         

+         
    
+             
    
+                 Transverse plane
+             
    
+         

+         

+             This option will realign the transverse plane in a fashion that closely
+             resembles to the MNI template. This will bring more consistent and visually
+             pleasing results.
+         

+         

+             Find the optimal transverse plane, the one that 
+                 cuts the
+                 brain with the biggest extent
+              (length x width). The search is
+             done with 2 parameters: 1 translation in Z (vertical ), 1
+             rotation around X.
+         

+         

+              
+         

+         

+             See an example here, with the found transverse plane superimposed in transparency:
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+              
+         

+         

+             Setting the origin
+         

+         

+             This step is not listed in the dialog box, because it is mandatory
+             and done all the time!
+         

+         

+              
+         

+         

+             We need to set a geometrical center for the brain, the point
+             from which the brain could best seen as fitting to a sphere (though
+             we do not explicitly do it). This is because the LSMAC
+             Lead Field model make use of a spherical model, and therefore
+             need a reasonable center to compute the relative radii between
+             solution points and electrodes.
+         

+         

+             In the usual case, the middle of the intersection line of the 
+                 sagittal
+                 plane and equatorial plane
+              is taken:
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+              
+         

+         

+             If only the sagittal or the equatorial planes have been
+             computed, the missing information is used from the 
+                 center of the
+                 brain's bounding box
+             , and sometimes the origin of the brain, if
+             it is set.
+         

+         

+             If neither the sagittal nor the equatorial planes have been
+             computed, the origin is the center of the brain's bounding box,
+             or the origin if it is set.
+         

+         

+              
+         

+         

+             
+                 We strongly recommend to always use 
+                     both
+                     planes detection
+                 , except for the MNI template which only needs
+                 the equatorial plane detection!
+             
+         

+         

+              
+         

+         

+             MRIs results
+         

+         

+             We are dealing here with the results of the 
+                 
+                     MRIs
+                     preprocessing
+                 
+              section only:
+         

+         
    
+             
  • 
+                 
    
+                     1 to 3 MRIs, depending to your inputs and processing options, saved in
+                     Nifti format;
+                 
    
+                 
      
+                     
    • 
+                         
      
+                             MRI file  basefilename.Head.nii  contains the full head;
+                         
      
+                     
    • 
+                         
      
+                             MRI file  basefilename.Brain.nii  contains the full head;
+                         
      
+                     
    • 
+                         
      
+                             MRI file  basefilename.Grey.nii 
+                             contains the grey mask;
+                         
      
+                 
    
+             
  • 
+                 
    
+                     MRIs can be resampled, reoriented, cropped and centered
+                     according to the given parameters;
+                 
    
+             
  • 
+                 
    
+                     These files are written unfiltered (filtering is used only at
+                     processing time).
+                 
    
+         

+         

+              
+         

+         

+             See some good examples of MRIs results:
+         

+         

+             Before the Sagittal & Equatorial search, reorientation,
+             and centering:
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+             And after the successful reorientation:
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+              
+         

+         

+             See some bad examples of MRIs results:
+         

+         

+             Here the Sagittal and Equatorial searches totally failed (this
+             is an example, which has been fixed since then):
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+             Electrodes preprocessing
+         

+         

+              
+         

+         

+             Electrodes input
+         

+         
+         

+             Electrodes coregistration
+         

+         
+         

+             Electrodes results
+         

+         
+         

+              
+         

+         

+             Electrodes input
+         

+         

+             You need 
+                 one 
+                     electrodes
+                     file
+                 
+              as input:
+         

+         
    
+             
  • 
+                 
    
+                     The surface electrodes of your recording
+                 
    
+             
  • 
+                 
    
+                     
+                         Any auxiliary / fiducial / funky electrode should be removed
+                         beforehand!
+                     
+                 
    
+         

+         

+              
+         

+         

+             Electrodes properties
+         

+         

+             The input electrodes should have the following properties:
+         

+         
    
+             
  • 
+                 
    
+                     File formats .xyz
+                     or .els.
+                 
    
+             
  • 
+                 
    
+                     Only the surface electrodes should be there, no
+                     auxiliaries, no landmarks etc...
+                 
    
+             
  • 
+                 
    
+                     The electrodes should cover as much surface as possible of the head.
+                     It might be a good idea to work with 257 electrodes f.ex. then remove some
+                     electrodes after the coregistration.
+                 
    
+             
  • 
+                 
    
+                     There should be enough electrodes, at least 64 and above.
+                 
    
+             
  • 
+                 
    
+                     It could be either an electrodes template, or the electrodes
+                     measured from a real head.
+                 
    
+                 
    
+                     In the latter case, the measures should be as accurate as possible,
+                     as this has a direct impact on the reliability of the inverse solutions!
+                 
    
+             
  • 
+                 
    
+                     The template should preferably be non-spherical, i.e. it is
+                     far better to have a real head shape.
+                     There are work-around, though.
+                 
    
+             
  • 
+                 
    
+                     Input orientation can be arbitrary, and can even be different from
+                     the orientation of the MRIs. This will be reworked during processing.
+                 
    
+         

+         

+              
+         

+         

+              
+         

+         

+             See some good examples of electrodes:
+         

+         

+             The first two are electrodes templates with different number of
+             electrodes, the third one is a subject's real electrodes, all of them
+             being OK:
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+              
+         

+         

+             See some bad examples of electrodes:
+         

+         

+             Not enough electrodes (29!), plus it has a spherical
+             shape. Don't even think of using this:
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+             Globally enough electrodes, but doesn't cover the head enough.
+             To totally avoid as inverses won't work properly:
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+             Enough electrodes, with a good coverage of the head, but has a 
+                 spherical
+                 shape
+             . This is not ideal, though you might be able to 
+                 proceed
+                 through
+             , but still not recommended:
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+             Real measured electrodes with heavily corrupted coordinates. Better use a template in this case:
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+             This is a good template file, but you need to remove the 
+                 lone
+                 electrodes / landmarks
+              that "float" below the surface:
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+              
+         

+         

+             Electrodes coregistration
+         

+         

+             Here are the available processing on the electrodes set.
+         

+         

+              
+         

+         

+             Doing nothing
+         

+         

+             Don't make use of the electrodes at all, so no Lead Field and
+             no Inverse Solution either...
+         

+         

+             Note: this is set from Presets list, there is no button for this.
+         

+         

+              
+         

+         

+             Electrodes already coregistered
+         

+         

+             Load and use the electrodes file, which should alreay fit exactly
+             on the Head MRI: same orientation, centering & scaling.
+         

+         

+             Note: if the MRIs are going through some geometrical transforms
+             (re-scaling, re-orientation, rotations etc...), then the same
+             transforms will be applied to the electrodes coordinates, as to
+             remain correctly coregistered.
+         

+         

+              
+         

+         

+             Interactive coregistration
+         

+         

+             The user has to manually coregister the electrodes set to the
+             head, in real time. It is his/her responsibility to make sure
+             the electrodes set is coregistered correctly: positioning the Fpz /
+             Cz / Oz electrodes, respecting the symmetry on the head etc...
+         

+         

+             It will launch the 
+                 
+                     Coregistration Toolbox
+                 
+             , and resume to the Inverse Matrices
+             toolbox soon after.
+         

+         

+              
+         

+         

+             Interactively refining an existing coregistration
+         

+         

+             This follows the exact same process as the 
+                 
+                     Interactive
+                     coregistration
+                 
+             , except that the electrodes model is loaded
+             as is, without computing a new center, orientation or size. It
+             assumes the model is already well adjusted to the head
+             surface, and only needs some slight adjustments.
+         

+         

+              
+         

+         

+             Electrodes results
+         

+         

+             We are dealing here with the results of the 
+                 
+                     Electrodes
+                     processing
+                 
+              section alone:
+         

+         
    
+             
  • 
+                 
    
+                     2 electrodes set, saved in .xyz format:
+                 
    
+                 
      
+                     
    • 
+                         
      
+                             One file  basefilename.xyz  is the one used for the
+                             actual IS computation, which should 
+                                 fit as much as possible the
+                                 surface of the head
+                             .
+                         
      
+                     
    • 
+                         
      
+                             One file  basefilename.For Display.xyz  is a
+                             modified version of the previous one, where the electrodes have been
+                             slightly pushed away from the surface, only to produce a more
+                             visually pleasing display when superimposed to the MRI.
+                         
      
+                         
      
+                             As its name implies, this version is for display use only,
+                             and should not be re-used for any computation!
+                         
      
+                 
    
+             
  • 
+                 
    
+                     Both sets are coregistered to
+                     the full head MRI;
+                 
    
+         

+         

+              
+         

+         

+             See some good examples of
+             electrodes set results:
+         

+         

+             The result from coregistering a template electrodes set to a real
+             head, with the results not glued to the surface.
+         

+         

+             First picture is the "official" result, and as it is so
+             close to the surface, you get this half-blent appearance, which is
+             normal. Second picture is the same with some depth-shifting
+             on the electrodes, for a better visual result. Third picture is the 
+                 
+                     For
+                     Display
+                 
+              version, more appropriate for display use:
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+              
+         

+         

+             See some bad examples of electrodes
+             set results:
+         

+         

+             Here is an example when just loading
+             an electrodes set and assuming it is coregistered, when indeed
+             it is not (guess the results won't be that good?):
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+              
+         

+         

+             Here is an example where gluing
+             should have been avoided, the electrodes landing inside the
+             head through the MRI's defect is not a good thing:
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+              
+         

+         

+             Solution Space
+         

+         

+              
+         

+         

+             Grey mask extraction
+         

+         
+         

+             Solution Points computation
+         

+         
+         

+             Loading Solution Points

+             Same Solution Points as Lead Field
+         

+         

+              
+         

+         

+              
+         

+         

+             The solution space is the next thing you need to work on after
+             the electrodes. It gives the positions of the points 
+                 where the
+                 inverse solution will be computed
+             .
+         

+         

+             The user can:
+         

+         
+         

+             This, together with the Lead Field options,
+             allows for all possible of combinations.
+         

+         

+              
+         

+         

+             Grey Mask extraction
+         

+         

+             Most of the time, we need a mask of the brain's grey matter:
+         

+         
+         

+              
+         

+         

+             (this step is performed automatically when 
+                 computing
+                 the Solution Points
+             , so there is no explicit option for this in
+             the dialog)
+         

+         

+              
+         

+         

+             Grey mask processing
+         

+         

+             Cartool processes the brain into a grey mask the following way:
+         

+         
    
+             
  • 
+                 
    
+                     Correcting for the Bias Field (optionally),
+                 
    
+             
  • 
+                 
    
+                     Estimating the global intensity distributions of the Grey /
+                     White / "Black" matters with a Mixture of Gaussians,
+                 
    
+             
  • 
+                 
    
+                     Classifying each voxel into Grey / White / "Black"
+                     matters by mixing:
+                 
    
+                 
      
+                     
    • 
+                         
      
+                             Gaussian probabilities based on intensity
+                         
      
+                     
    • 
+                         
      
+                             Neighbors likelihood (more grey neighbors -> higher chance
+                             to be grey, too)
+                         
      
+                 
    
+             
  • 
+                 
    
+                     Smoothing / filling holes of the resulting grey mask. This step is
+                     quite important before the ensuing downsampling to solution points!
+                 
    
+         

+         

+              
+         

+         

+             Note that this conversion can also be ran from the MRI Window, with
+             the  
+                 Filters | Brain
+                 processing | Segment to Grey Matter
+               menu, and choosing
+             the Regular or Fat method.
+         

+         

+              
+         

+         

+             See here an example of the grey mask extraction:
+         

+         

+             
+         

+         

+              
+         

+         

+             Grey mask vs Grey matter
+         

+         

+             The grey mask extracted by Cartool is thicker than your
+             usual grey matter, which can be quite thin near some given
+             areas of the brain.
+         

+         

+             This is an important point, as smoothing is always required 
+                 before
+                 correctly downsampling
+              to Solution Points. Otherwise we end up
+             with aliasing effects (Nyquist theorem) of the solution space:
+             missing points where the spatial frequency is below the downsampling
+             spatial frequency. So please keep in mind that the grey mask
+             extraction is more than a grey matter extraction, and 
+                 is
+                 better done the "Cartool way" to ensure a correct solution space
+             .
+         

+         

+              
+         

+         

+             See here an example of a subject's Grey matter (on the left), and the
+             corresponding Grey mask from Cartool (on the right):
+         

+         

+             
+         

+         

+              
+         

+         

+             Whole brain as grey mask
+         

+         

+             There are some cases where the usual Grey mask extraction will fail. The most
+             common cases are when the histograms of the Grey vs White matters are not
+             correctly estimated: for newborns, or animals like monkeys or mice.
+         

+         

+             In that case, just use the option to compute the grey mask on the whole
+             brain. It will still poke out the csf parts, but after downsampling you might
+             get solution points in the Black matter (csf). It doesn't harm the inverse
+             solution whatsoever, and the inverse shouldn't give you any significatn
+             results in those points.
+         

+         

+              
+         

+         

+             Here is an example on newborn, first showing the Grey mask, then the brain
+             with the superimposed solution points:
+         

+         

+             Grey mask on the whole brain of newborn
+         

+         

+              
+         

+         

+              
+         

+         

+             Solution Points computation
+         

+         

+             The Grey mask is basically downsampled
+             (with great care) into the Solution Points the following way:
+         

+         
    
+             
  • 
+                 
    
+                     Run a downsampling loop, with a non-integer downsampling factor:
+                 
    
+                 
      
+                     
    • 
+                         
      
+                             Downsample the grey mask, centered around the geometrical center,
+                         
      
+                     
    • 
+                         
      
+                             Remove voxels with less than 8 neighbors out of 26,
+                         
      
+                     
    • 
+                         
      
+                             Count remaining voxels,
+                         
      
+                         
        
+                             
      • 
+                                 
        
+                                     if close enough to the desired results, exit the downsampling loop,
+                                 
        
+                             
      • 
+                                 
        
+                                     otherwise, slightly adjust the downsampling factor and repeat the loop
+                                 
        
+                         
      
+                 
    
+         

+         

+              
+         

+         

+              
+         

+         

+             See here an example of a slice of a grey mask, with the corresponding
+             converted SPs on top:
+         

+         

+             
+         

+         

+              
+         

+         

+              
+         

+         

+             Actually, the Solution Points extraction is an important step
+             of the Inverse Solutions, very often overlooked, if not totally
+             ignored in the literature. Here are some points which Cartool is
+             especially taking care of.
+         

+         

+             SPs Left-right distribution
+         

+         

+             First, remember that the MRIs should have been 
+                 aligned
+                 with their midsagittal plane
+             . That means the 
+                 
+                     geometrical
+                     center
+                 
+              of the MRIs is going through a YZ plane (the
+             midsagittal plane) that cuts the brain in two (nearly) equal parts.
+         

+         

+             When downsampling the grey matter into the SPs, the new 
+                 SPs
+                 downsampled center
+              has to remain through this midsagittal plane.
+             This way will ensure that the resulting SPs distribution will be
+             optimally distributed across the midsagittal plane, with 
+                 no side
+                 receiving more SPs than the other one
+             .
+         

+         

+             Otherwise, having an asymmetrical distribution of SPs will have a
+             dramatic impact on the inverse solutions, with more weights given to
+             one side of the brain, or even results that could be assigned the 
+                 wrong
+                 side of the brain
+             ! Of course, a real asymmetrical
+             (pathological) brain will have its midsagittal plane set according to
+             its anatomy, and will have an asymmetrical distribution of
+             SPs. The point is, the distribution of SPs has to reflect the
+             reality, and not to artificially favor one side over the other.
+         

+         

+              
+         

+         

+             See here an incorrectly downsampled grey mask (on the left), with too
+             many SPs on the right side (especially near the midsagittal plane),
+             and a correct one (on the right), with the little remaining
+             left-right differences stemming from the actual shape of the brain:
+         

+         

+             
+         

+         

+              
+         

+         

+             SPs Minimum neighborhood
+         

+         

+             The inverse process will later need the computation of a discrete Laplacian
+             in the Solution Space. To be able to do that correctly, each solution
+             point has to have enough neighbors. We drew a quite
+             conservative limit for each Solution Point to have at least 
+                 8
+                 neighbors out of 26
+             , and the ones who don't fulfill this
+             criterion to be removed.
+         

+         

+              
+         

+         

+             SPs Continuity
+         

+         

+             With this method, we aim to 
+                 have SPs
+                 even in the thinnest parts
+              of the grey matter, and to have an 
+                 even
+                 coverage
+              of the grey matter as a whole. It should be obvious
+             that there can not be any inverse solution results on non-existent
+             SPs (!), resulting in a lack of precision for some brain areas.
+         

+         

+             Another risk, if some SPs were to be missing in some grey matter
+             parts, and some brain activity were to be coming from these very same
+             areas, would be that the closest SPs to the missing parts
+             would be ellicited by the inverse solution. But the closest SPs might
+             prove to be not good enough, like being too far, or being on
+             the other hemisphere f.ex.
+         

+         

+              
+         

+         

+             See here an example of a bad SPs distribution (on the left), with SPs
+             missing in the occipital and frontal parts, and a better distribution
+             (on the right), without holes and with a fuller coverage:
+         

+         

+             
+         

+         

+              
+         

+         

+             Number of SPs
+         

+         

+             Choosing the number of SPs is up to the user, with a recommended
+             range from 3000 to 6000, and a default set to 6000.
+         

+         

+              
+         

+         

+             There are pros and cons for both low and high number of SPs, some
+             being more or less obvious:
+         

+         

+             
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+             

+                         
    
+                             
    
+                                 Lower number of SPs
+                     

+                         
    
+                             
    
+                                 Higher number of SPs
+                     

+                         

+                             (+) Faster to compute the matrices
+                         

+                         

+                             (+) Less memory
+                         

+                         

+                             (+) Less numerical precision issues
+                         

+                         

+                             (+) Smaller matrices & Faster display
+                     

+                         

+                             (-) Longer to compute the matrices
+                         

+                         

+                             (-) More memory
+                         

+                         

+                             (-) More numerical precision issues
+                         

+                         

+                             (-) Bigger matrices & Slower display
+                     

+                         

+                             (-) Less spatial resolution
+                         

+                         

+                             (-) Less spatial accuracy
+                         

+                         

+                             (-) Less neighbors around each SPs
+                     

+                         

+                             (+) More spatial resolution
+                         

+                         

+                             (+) Somehow more spatial accuracy
+                         

+                         

+                             (+) More neighbors around each SPs
+                     

+         

+         

+              
+         

+         
    
+             
  • 
+                 
    
+                     Speed is only a slight annoyment. If you are in a hurry for
+                     some reasons, use something like 3000 SPs. Otherwise, run it during a
+                     break, 5000 SPs and 257 electrodes should be done in about 10 minutes
+                     per matrix, 6000 SPs in about 30 minutes.
+                 
    
+             
  • 
+                 
    
+                     Memory issue is a real problem. If you encounter some
+                     problems, make sure your machine has enough of physical memory, is
+                     healthy and set correctly (see 
+                         Setting
+                         your machine correctly
+                     ). If the problems remain, try to reduce
+                     the number of SPs, from 5000 down to 3000.
+                 
    
+             
  • 
+                 
    
+                     Numerical precision issues come from the fact that inverting
+                     huge matrices will cumulate more errors than for smaller ones.
+                     However, this shouldn't be a real problem here, and nothing can be
+                     really done about that in the realm of digital computers.
+                 
    
+             
  • 
+                 
    
+                     Bigger matrices shouldn't be a real concern with our current
+                     storage capacity. However, a higher number of SPs can be slightly
+                     detrimental to the speed of the inverse display,
+                     as there are more rows to compute from the inverse matrix.
+                 
    
+                 
    
+                      
+                 
    
+                 
    
+                     Now, about the sensitive topics of spatial resolution (grid
+                     spacing) and accuracy (to be spot-on). If first recommend you
+                     to get an idea of 
+                         
+                             what
+                             these terms really mean
+                         
+                     .
+                 
    
+             
  • 
+                 
    
+                     More points means more spatial resolution, always,
+                     as the resulting grid spacing will be smaller.
+                 
    
+             
  • 
+                 
    
+                     More points also means more accuracy, but up to a limit.
+                     First, accuracy can not be better than the resolution. So you have
+                     to increase the number of points to also increase the accuracy. But 
+                         accuracy
+                         will stop improving
+                      past a given number of SPs (i.e. the inverse
+                     solution is not "getting better"), somehow due to the fact
+                     that the quantity of information inputted into the system remains the
+                     same, and is set by the number of electrodes. Also, the matrix
+                     inversion process can intrinsically provide only a given level of accuracy.
+                 
    
+                 
    
+                     To summarize, from our experience, the range 3000 to 6000 SPs seems
+                     correct for regular adult human brains.
+                 
    
+             
  • 
+                 
    
+                     As said earlier, there needs to be 
+                         
+                             enough
+                             neighbors around each SP
+                         
+                     . And the more SPs, the more
+                     neighbors there are for each SP. Again, 3000 looks like a minimum
+                     value here.
+                 
    
+         

+         

+              
+         

+         

+             SPs Results
+         

+         

+             When computing the Solution Points, you'll have the following results:
+         

+         
+         

+              
+         

+         

+             Some remarks about the output of the Solution Points extraction:
+         

+         
    
+             
  • 
+                 
    
+                     Points are regularly spaced on a grid, but may not be aligned
+                     on MRI's voxels nor X/Y/Z axis.
+                 
    
+             
  • 
+                 
    
+                     SPs are named according to which octant they belong to:
+                 
    
+                 
      
+                     
    • 
+                         
      
+                             First, 3 letters within Left/Right, Posterior/Anterior
+                             and Inferior/Superior
+                         
      
+                         
      
+                             (like in "LAS" for the Left Anterior Superior),
+                         
      
+                     
    • 
+                         
      
+                             Followed by a number within that particular octant
+                         
      
+                         
      
+                             (like in "LAS123" for the 123th point).
+                         
      
+                 
    
+         

+         

+              
+         

+         

+             See this paragraph about 
+                 all
+                 combinations of Solution Points / Lead Field options
+             .
+         

+         

+              
+         

+         

+             Loading Solution Points
+         

+         

+             Use this option with care, Cartool will load your file
+             "as is", so it better had to have these properties:
+         

+         
    
+             
  • 
+                 
    
+                     It should be in the 
+                         same space as the MRI Head / Brain /
+                         Electrodes XYZ
+                     ;
+                 
    
+             
  • 
+                 
    
+                     It should be topologically fit for the 
+                         inversion
+                         step
+                     :
+                 
    
+                 
      
+                     
    • 
+                         
      
+                             Points should be inside  the brain, and preferably in the 
+                                 grey
+                                 matter
+                              (though having points in the white matter is no big
+                             deal). However, points outside the brain will certainly
+                             produce an erroneous Lead Field and inverse matrix.
+                         
      
+                     
    • 
+                         
      
+                             Points should be aligned on a grid, but this grid is not
+                             required to be aligned on the X/Y/Z axis, nor to land exactly on the
+                             MRI voxels center.
+                         
      
+                     
    • 
+                         
      
+                             Each point should have at least a few neighbors (at least 1!),
+                             to be able to compute some neighborhood constraints, like a Laplacian.
+                         
      
+                     
    • 
+                         
      
+                             Left-right distribution should be balanced
+                             and reflect the actual distribution of the grey matter, especially
+                             near the mid-sagittal cutting plane. If the points are not
+                             symetrically distributed, some locations will be missing and the
+                             Laplacian will not be correct, too.
+                         
      
+                 
    
+         

+         

+              
+         

+         

+             Loading a Solution Points file is of interest if you want to compare
+             different Lead Fields, while keeping the inverse space constant.
+         

+         

+             Also, see this paragraph about 
+                 all
+                 combinations of Solution Points / Lead Field options
+             .
+         

+         

+              
+         

+         

+             Here is an example of re-loading a qualified 
+                 Cartool-computed
+                 solution space
+             , on top of the brain:
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+              
+         

+         

+             And here is an example of re-loading a 
+                 Cartool-computed
+                 solution space
+             , on top of an 
+                 existing
+                 Lead Field
+              (a typical case for 
+                 Lead
+                 Field interpolation
+             ):
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+              
+         

+         

+             Same Solution Points as Lead Field
+         

+         

+             If you are reloading a Lead Field,
+             with its associated Solution Points file,
+             you can simply tell Cartool to use it as the output solution space.
+         

+         

+             In case the amount of Solution Points is too high, you can
+             (approximately) downsample the solution space and the 
+                 
+                     Lead
+                     Field
+                 
+              to a given number of points.
+         

+         

+              
+         

+         

+             Also, see this paragraph about 
+                 all
+                 combinations of Solution Points / Lead Field options
+             .
+         

+         

+              
+         

+         

+             See here an example of (heavy) downsampling, from 150'000 points to
+             about 3'000:
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+              
+         

+         

+             Lead Field processing
+         

+         

+              
+         

+         

+             What is the Lead Field

+             Lead Field input

+             Lead Field computation
+         

+         
+         
+         

+             Loading the Lead Field from file
+         

+         
+         

+             Lead Field results
+         

+         

+              
+         

+         

+             What is the Lead Field (LF)
+         

+         

+             The Lead Field K (sometimes called the Forward Solution
+             as opposed to the Inverse Solution) is a matrix that embodies
+             the physical relations that exist between the 
+                 current
+                 sources in the brain
+              and the electrical potentials on the surface,
+             as picked up by the electrodes. It is made up of:
+         

+         
    
+             
  • 
+                  the 
+                     geometrical relationship between the solution points
+                     and the electrodes
+                 , i.e. how far and at which angles they lie
+                 respectively;
+             
    • 
+             
  • 
+                 and electromagnetic laws, i.e. how the
+                 electromagnetic field propagates through different media, and the
+                 resulting voltage on a receiving electrode.
+             
    • 
+         

+         

+             This matrix is used at the core of the 
+                 Inverse
+                 Solution
+             , and the accuracy of its construction will be directly
+             reflected in the inverse solutions. See here an example of how one
+             frontal electrode (yellow) will get most of its potentials from solution points which
+             dipoles align with the red vectors:
+         

+         

+             
+         

+         

+              
+         

+         

+             There is certainly a trade-off between the complexity
+             of the model, the amount of parameters to know and adjust, the time
+             and ease to compute it, and its effectiveness in the
+             whole Inverse Solutions scheme. For sure, the more realistic and the
+             more parameters there are, the better the model should be. But there
+             are also practical issues, like the speed of computation, the reliability of
+             the results, the real
+             contribution of a more complex model as compared to a simpler one. Last but
+             not least, not all physical parameters (like the
+             
+                 skull
+                 conductivity
+             ) are well known for the moment.
+         

+         

+              
+         

+         

+             Lead Field input
+         

+         

+             To actually compute the
+             Lead Field in Cartool, you only need:
+         

+         
+         

+              
+         

+         

+             Or you can otherwise reload
+             an existing LF, in which case you need:
+         

+         
+         

+              
+         

+         

+             Lead Field computation
+         

+         

+             Computing the Lead Field can be split into a geometrical part,
+             and an electromagnetic part:
+         

+         
+         

+              
+         

+         

+             You can also visit this paragraph about 
+                 all
+                 combinations of Solution Points / Lead Field options
+             .
+         

+         

+              
+         

+         

+             LSMAC geometrical model
+         

+         

+             The LSMAC geometrical model is basically a way to transform
+             the real head shape into some intermediate local spherical model.
+             Because it is done with different parameters for each electrode position, it
+             preserves many of the original head properties, like local thicknesses.
+         

+         

+             Also note that this step is totally independent to the electromagnetic model
+             and its number of layers.
+         

+         

+              
+         

+         

+             Here we can see f.ex. how the spherical parameters will be different for
+             different 2 electrodes (in yellow):
+         

+         

+             
+         

+         

+              
+         

+         

+             See the article for an introduction to the method:

+              
+         
"Spatiotemporal Analysis of Multichannel EEG: CARTOOL",
Denis Brunet, Micah M. Murray, Christoph M. Michel,
Computational Intelligence and Neuroscience, 2011.

+             The idea is to push the spherical model to the limit of its
+             capabilities, while keeping the benefits of its equations (relative!)
+             simplicity. It can be thought of a sort of BEM model, as it
+             approximates the boundaries of the brain and skull.
+         

+         

+              
+         

+         
    
+             
    
+                 LSMAC Spherization step
+             
    
+         

+         

+             The LSMAC processing pipe-line is very similar to the older (and obsolete) SMAC model:
+         

+         

+              
+         

+         

+             MRIs & Electrodes -> Extract Gey mask & Solution Points,
+             Compute Laplacian -> Compute Scalp / Skull / CSF / Brain radii & Spherical
+             Model, for each
+             electrode -> Compute LF
+         

+         

+              
+         

+         

+             It is important to note that a 
+                 spherical model
+                 is computed underneath each electrode
+             , so the global model accounts
+             for the real scalp / skull / CSF / brain radii, as a BEM model would.
+         

+         

+              
+         

+         
    
+             
    
+                 LSMAC Spherization function
+             
    
+         

+         

+             A global spherization model is computed by fitting a parametric model to the
+             scalp. It is then used to convert the head to a sphere, with internal skull,
+             CSF and brain boundaries adjusted for each electrode.
+         

+         

+             See here the spherization sequence done in Cartool, showing: the full
+             MRI fitted with a scalp model, and how the model warps into a sphere.
+         

+         

+             

+             
+         

+         

+              
+         

+         

+             Tissues boundaries estimated from MRI
+         

+         

+             The electromagnetic models will need
+             to know the boundaries of either 3 or 4 of the following layers: scalp,
+             skull, CSF and brain layers. When only 3 layers are actually needed, then the brain and CSF
+             will be merged into as a single layer with
+             weighted average conductivity.
+         

+         

+             When this option is checked,
+             Cartool will estimate the radii
+             of the skull, CSF and brain under each electrode from the provided T1 MRI.
+         

+         

+              
+         

+         

+             Note that in case the skull has been operated and still has some open holes in it, you might
+             want to switch off this option by using one of the Lead Field Preset. In this case, predefined,
+             constant radii will be used in the model. Of course, this should be used only
+             as a last resort...
+         

+         

+              
+         

+         

+             Also note that scanning through a T1 MRI is quite a difficult task, and will
+             essentially provide relative thicknesses. To recalibrate these 
+                 relative thicknesses
+              into absolute thicknesses, Cartool will
+             use the table shown below.
+         

+         

+              
+         

+         

+             Here is an example of the 4-Shell surfaces extracted from the T1 MRI (left),
+             and a close-up to 4 electrodes with their corresponding positions shown at
+             each layer underneath (right):
+         

+         

+             
+         

+         

+         

+         
    
+             
    
+                 Skull estimation for each electrode
+             
    
+         

+         

+             For the Lead Field computation, Cartool needs only the skull
+             information below each electrode locus, and not for the
+             entire head.
+         

+         

+             To do so, Cartool extracts a radial sample, from the electrode
+             position to the geometrical center, looks
+             for a type of valley pattern in the intensity levels near the
+             expected bone, and takes the edges of this valley as the skull boundaries.
+         

+         

+              
+         

+         

+             See here an example of the relative radii of the inner and outer
+             parts of the skull, for 257 electrodes, some of which being on the
+             cheek and near the neck (100% corresponds to the electrode distance):
+         

+         

+             
+         

+         

+             This example shows clearly the advantage of adapting the
+             scalp/skull/brain radii according to each electrode, as the inner
+             skull radii vary from 35% to 85%, and the outer part from 42% to 92%.
+         

+         

+              
+         

+         
    
+             
    
+                 Layers estimates output
+             
    
+         

+         

+             Some remarks about the output of the Skull estimation:
+         

+         
+         

+         

+         

+             Tissues boundaries computed from
+             segmented tissues file
+         

+         

+             Better than estimating the 
+                 boundaries from the T1
+                 MRI
+             , user can provide a volume with each voxel labeled as a given tissue
+             index.
+         

+         

+              
+         

+         

+             Example of a segmented tissues file (MNI):
+         

+         

+             
+         

+         

+         

+         

+             Tissues indexes are stored in the associated <same file name>.txt file, and is currently
+             accounting for 14 different tissues:
+         

+         
1 Scalp
 2 Fat
 3 Muscle
 4 CSF
@@ -2531,187 +3520,258 @@ 

 12 Brain
 13 Grey
 14 White

-  

-  

-   Age to skull thickness

-  

-   The skull goes through a lot of changes across age, especially from newborn 
-   up to 17 years old. Its thickness increases over the time, while its relative 
-   conductivity to an electromagnetic signal also decreases.

-  

-   Unfortunately, both thickness and relative conductivity are needed to
-   compute a reliable the Lead Field. To increase 
-   the confidence in the model, the user has now to specify the targeted age for 
-   its inverse solution. Cartool then uses two tables to convert the age to mean 
-   thickness and age to conductivity, then updates these two fields in the 
-   dialog.

-  

-    

-  

-   Here is the age to thickness curve, with age ranging from birth to 100 years, 
-   and thickness in [mm]:

-  

-   Age to skull thickness

-  

-    

-  

-   This curve was built from these 2 data sets, the first one on 0 to 20 yo, the 
-   second above 20 yo:

-  

-   "Increase in cranial thickness during growth,"

-   A. F. Roche, ,
Hum. Biol., 
-   vol. 25, pp. 81-92, May 1953.


"Evaluation of Skull Cortical Thickness 
-   Changes With Age and Sex From Computed Tomography Scans",
E. 
-   M. Lillie, J. E. Urban, S. K. Lynch, A. A. Weaver, and J. D. Stitzel,
J. Bone Miner. Res., 
-   vol. 31, pp. 299-307, Feb 2016.

-  

-   Note that Cartool first estimate the skull from the 
-   T1. Then it adjusts the global thickness according to the curve above. 
-   This could be taken advantage of, f.ex. if one only has an adult template at 
-   hand, but still needs an inverse for some younger individuals. By using the 
-   adult template, and forcing the mean thickness to be thinner, user can 
-   achieve a better estimate of the Lead Field (also, templates for all sorts of 
-   age exist nowadays).

-  

-   Age to skull & other conductivities

-  

-   There is a field to specify the absolute conductivity of the skull, 
-   in [S/m]. Also see the 
-   paragraph above about skull thickness.

-  

-    

-  

-   It is usually automatically set from the following age to conductivity curve 
-   (unit in [S/m]), with age ranging from birth 
-   to 100 years:

-  

-   Age to skull conductivity

-  

-    

-  

-   The other tissues conductivities have been set to (using the McCann reference 
-   below, but may change in the future):

-  

-    

-  
-	  
-		  
-		  
-	  
-	  
-		  
-		  
-	  
-	  
-		  
-		  
-	  
-	  
-		  
-		  
-	  
-	  
-		  
-		  
-	  
-	  
-		  
-		  
-	  
-  
TissueConductivity, in 
-		  [S/m]
White Matter0.1462
Grey Matter0.3787
Blood0.5737
CSF1.7358
Scalp0.4137

-  

-    

-  

-   Literature is very scarse on the estimation of the live skull conductivity. 
-   Old numbers were estimated from cadavers, and were proven to be way to low as 
-   to live ones. Herer are the references that have been used:

-  

-   "Variation in reported human head tissue electrical 
-   conductivity values",
H. McCann, G. Pisano, L.  Beltrachini,

-   Brain Topography, 2019 & 2021


"Measurement of the conductivity of skull, 
-   temporarily removed during epilepsy surgery",
R. Hoekema, G. 
-   H. Wieneke, F. S. Leijten, C. W. van Veelen, P. C. van Rijen, G. J. Huiskamp, 
-   et al.,
Brain Topogr., vol. 16, pp. 
-   29-38, Fall 2003.

-  

-    

-  

-   Electromagnetic equations

-  

-   Once assumed within a (local) spherical model, the
-   tissues thicknesses and
-   conductivities estimated, Cartool 
-   can proceed with the electromagnetic models, with the following optinos 
-   available:

-  
-  

-   

-  

-   Ary approximation

-  

-   Note: this model is obsolete and is still there for backward 
-   compatibility only. Use the more precise exact 
-   equations below.

-  

-   For the old Ary, isotropic 3-Shell model (only), Cartool uses an 
-   approximation to the exact analytic solutions to the electromagnetic 
-   equations.

-  

-   It essentially replaces a dipole in a 3-Shell model by an equivalent dipole 
-   in a 1-Shell model, which equations are much easier to compute. The 
-   equivalent dipole is the original dipole, but shifted a little deeper into 
-   the brain. The radii ratio between the original and shifted dipoles will 
-   depend on the relative conductivities of the skull to the ( scalp + brain + 
-   CSF ) layers, among many things.

-  

-   There also exist improvements to this method, f.ex. by Scherg & Berg, or Zhi 
-   Zhang.

-  

-   This Ary method has been the one in used since the early days of Cartool, and 
-   has proven to be quite robust.

-  

-   

-  

-   Reference:
"Location of Sources of Evoked Scalp Potentials: Corrections for Skull and Scalp Thicknesses",
James P. Ary, Stanley A. Klein, Derek H. Fender,
Biomedical Engineering, Vol. BME-28, No6, June 1981.
 
- 
Niedermeyer's Electroencephalography, chapter 55 "EEG Mapping and Source Imaging",
Chr. Michel, B. He,
Lippincott Williams & Wilkins, 2010.
 
- 
Electrical Neuroimaging,
Chr. Michel, Th. Koenig, D. Brandeis, L.R.R. Gianotti and J. Wackermann,
Cambridge University Press, 2009.

-  

-   

-  

-   Exact analytic equations

-  

-   The full, exact, analytic solutions equations for any number of 
-   isotropic layers has been implemented since 2021. It is currently used for 
-   3-Shell model,
-   4-Shell model and 6-Shell models:

-  
    
-	  
  • 3-Shell model is made of brain, skull and scalp layers;
    • 
-	  
  • 4-Shell model is made of brain, CSF, skull and scalp layers;
    • 
-	  
  • 6-Shell model is made of brain, CSF, skull compact, skull spongy, 
-	  skull compact and scalp layers.
    • 
-  

-  

-    

-  

-   This one does not make use of any approximations, for the 
-   spherical case. It gives the exact 
-   potential from the exact (spherical) positions of both the solution point and the 
-   electrode, and through any number of isotropic spherical layers. It is therefore 
-   logically expected to give better 
-   results than the Ary 3-Shell approximation. Although it involves two double recursive 
-   Lagrange 
-   formulas, its implementation runs pretty fast anyway.

-  

-   

-  

-   The formulas for the 4-Shell model can be found in (note there is an 
-   error in the general formula, corrected in Nunez & Srinivasan book):
"A fast method to compute surface potentials generated by dipoles within multilayer anisotropic spheres",
+         

+         

+             Age to skull thickness
+         

+         

+             The skull goes through a lot of changes across age, especially from newborn
+             up to 17 years old. Its thickness increases over the time, while its relative
+             conductivity to an electromagnetic signal also decreases.
+         

+         

+             Unfortunately, both thickness and relative conductivity are needed to
+             compute a reliable the Lead Field. To increase
+             the confidence in the model, the user has now to specify the targeted age for
+             its inverse solution. Cartool then uses two tables to convert the age to mean
+             thickness and age to conductivity, then updates these two fields in the
+             dialog.
+         

+         

+              
+         

+         

+             Here is the age to thickness curve, with age ranging from birth to 100 years,
+             and thickness in [mm]:
+         

+         

+             Age to skull thickness
+         

+         

+              
+         

+         

+             This curve was built from these 2 data sets, the first one on 0 to 20 yo, the
+             second above 20 yo:
+         

+         

+             "Increase in cranial thickness during growth,"

+             A. F. Roche, ,
Hum. Biol.,
+             vol. 25, pp. 81-92, May 1953.



+                 "Evaluation of Skull Cortical Thickness
+                 Changes With Age and Sex From Computed Tomography Scans",

+             E.
+             M. Lillie, J. E. Urban, S. K. Lynch, A. A. Weaver, and J. D. Stitzel,
J. Bone Miner. Res.,
+             vol. 31, pp. 299-307, Feb 2016.
+         

+         

+             Note that Cartool first estimate the 
+                 skull from the
+                 T1
+             . Then it adjusts the global thickness according to the curve above.
+             This could be taken advantage of, f.ex. if one only has an adult template at
+             hand, but still needs an inverse for some younger individuals. By using the
+             adult template, and forcing the mean thickness to be thinner, user can
+             achieve a better estimate of the Lead Field (also, templates for all sorts of
+             age exist nowadays).
+         

+         

+             Age to skull & other conductivities
+         

+         

+             There is a field to specify the absolute conductivity of the skull,
+             in [S/m]. Also see the
+             paragraph above about skull thickness.
+         

+         

+              
+         

+         

+             It is usually automatically set from the following age to conductivity curve
+             (unit in [S/m]), with age ranging from birth
+             to 100 years:
+         

+         

+             Age to skull conductivity
+         

+         

+              
+         

+         

+             The other tissues conductivities have been set to (using the McCann reference
+             below, but may change in the future):
+         

+         

+              
+         

+         
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+         
Tissue
+                     
+                         Conductivity, in
+                         [S/m]
+                     
+                 
White Matter0.1462
Grey Matter0.3787
Blood0.5737
CSF1.7358
Scalp0.4137

+         

+              
+         

+         

+             Literature is very scarse on the estimation of the live skull conductivity.
+             Old numbers were estimated from cadavers, and were proven to be way to low as
+             to live ones. Herer are the references that have been used:
+         

+         

+             
+                 "Variation in reported human head tissue electrical
+                 conductivity values",

+             H. McCann, G. Pisano, L.  Beltrachini,

+             Brain Topography, 2019 & 2021



+                 "Measurement of the conductivity of skull,
+                 temporarily removed during epilepsy surgery",

+             R. Hoekema, G.
+             H. Wieneke, F. S. Leijten, C. W. van Veelen, P. C. van Rijen, G. J. Huiskamp,
+             et al.,
Brain Topogr., vol. 16, pp.
+             29-38, Fall 2003.
+         

+         

+              
+         

+         

+             Electromagnetic equations
+         

+         

+             Once assumed within a (local) spherical model, the
+             tissues thicknesses and
+             conductivities estimated, Cartool
+             can proceed with the electromagnetic models, with the following optinos
+             available:
+         

+         
+         

+         

+         

+             Ary approximation
+         

+         

+             Note: this model is obsolete and is still there for backward
+             compatibility only. Use the more precise 
+                 exact
+                 equations below
+             .
+         

+         

+             For the old Ary, isotropic 3-Shell model (only), Cartool uses an 
+                 approximation to the exact analytic solutions
+              to the electromagnetic
+             equations.
+         

+         

+             It essentially replaces a dipole in a 3-Shell model by an equivalent dipole
+             in a 1-Shell model, which equations are much easier to compute. The
+             equivalent dipole is the original dipole, but shifted a little deeper into
+             the brain. The radii ratio between the original and shifted dipoles will
+             depend on the relative conductivities of the skull to the ( scalp + brain +
+             CSF ) layers, among many things.
+         

+         

+             There also exist improvements to this method, f.ex. by Scherg & Berg, or Zhi
+             Zhang.
+         

+         

+             This Ary method has been the one in used since the early days of Cartool, and
+             has proven to be quite robust.
+         

+         

+             

+         

+         

+             Reference:
+         
"Location of Sources of Evoked Scalp Potentials: Corrections for Skull and Scalp Thicknesses",
James P. Ary, Stanley A. Klein, Derek H. Fender,
Biomedical Engineering, Vol. BME-28, No6, June 1981.
 
+         
Niedermeyer's Electroencephalography, chapter 55 "EEG Mapping and Source Imaging",
Chr. Michel, B. He,
Lippincott Williams & Wilkins, 2010.
 
+         
Electrical Neuroimaging,
Chr. Michel, Th. Koenig, D. Brandeis, L.R.R. Gianotti and J. Wackermann,
Cambridge University Press, 2009.

+         

+         

+         

+             Exact analytic equations
+         

+         

+             The 
+                 full, exact, analytic solutions equations for any number of
+                 isotropic layers
+              has been implemented since 2021. It is currently used for
+             3-Shell model,
+             4-Shell model and 6-Shell models:
+         

+         
    
+             
  • 3-Shell model is made of brain, skull and scalp layers;
    • 
+             
  • 4-Shell model is made of brain, CSF, skull and scalp layers;
    • 
+             
  • 
+                 6-Shell model is made of brain, CSF, skull compact, skull spongy,
+                 skull compact and scalp layers.
+             
    • 
+         

+         

+              
+         

+         

+             This one does not make use of any approximations, for the
+             spherical case. It gives the 
+                 exact
+                 potential from the exact (spherical) positions of both the solution point and the
+                 electrode, and through any number of isotropic spherical layers
+             . It is therefore
+             logically expected to give better
+             results than the Ary 3-Shell approximation. Although it involves two double recursive
+             Lagrange
+             formulas, its implementation runs pretty fast anyway.
+         

+         

+             

+         

+         

+             The formulas for the 4-Shell model can be found in (note there is an
+             error in the general formula, corrected in Nunez & Srinivasan book):
+         
"A fast method to compute surface potentials generated by dipoles within multilayer anisotropic spheres",
 Zhi Zhang,
 Phys. Med. Biol. 40, 1995.
  
@@ -2719,518 +3779,724 @@ 

 "Electric Fields of the Brain - The Neurophysics of the EEG",
 Paul L. Nunez, Ramesh Srinivasan,
 Oxford University Press, 2nd Ed. 2006.

-  

-    

-  

-   Loading the Lead Field from file

-  

-   The Lead Field (aka Forward model) can be reloaded from an external
-    file. The main reasons could be:

-  
    
-   
  • 
-   
    
-    You computed a LF with another model (like BEM 
-    or FEM), and want to plug it into the inversion step of Cartool,
    
-   
  • 
-   
    
-    Or you just want to re-use the LF computed by an earlier run of Cartool,
-     hence saving time.
    
-   

-  

-    

-  

-   See this paragraph about all 
-   combinations of Solution Points / Lead Field options.

-  

-    

-  

-   Loading Lead Field - Input files

-  

-   You need two input files:

-  
-  

-    

-  

-   Lead Field results

-  

-   Only if you have computed the LF, 
-   you'll have the following results:

-  
    
-   
  • 
-   
    
-    Some boundary files,
    
-   
  • 
-   
    
-    The  .lf  
-    Lead Field matrix that can be re-used for later computations (technically 
-	saved as double precision).
    
-   
  • 
-   
    
-    The .ris file also 
-    contains a copy of the Lead Field, which can be used both for display 
-    and for later reloading (saved as single precision).
    
-   
  • 
-   
    
-    For display purpose only, the Lead Field matrix converted into an 
-	.sef 
-    file. It can be used to display as a map how each SP influences all electrodes.
    
-   
    
-    It only holds the norm of the vectorial Lead Field, per SP, once transposed.
    
-   
  • 
-   
    
-    The .vrb verbose 
-    file contains some detailed results from the optional radii
-     from skull computation (scalp and skull radii and thicknesses).
    
-   

-  

-    

-  

-   Solution Points and Lead Field cases

-  

-   All combinations of Solution Points and 
-   Lead Field cases
Interpolating a Lead Field

-   Downsampling a Lead Field

-   Neutralizing some solution points

-  

-   All combinations of Solution Points and 
-   Lead Field cases

-  

-   Cartool allows all possible combinations between computing / 
-   loading Solution Points, and computing / loading Lead Field.
-    Here is a table to sort out all these cases and explain their 
-   meaning and consequences:

-  

-    

-  
-  

-    

-  

-   Here are also the recommended scenarios, by decreasing order of 
-   results quality:

-  
    
-   
  1. 
-   
    
-    Computing Solution Points + Computing Lead Field
    
-   
  2. 
-   
    
-    Computing Solution Points + Loading & Interpolating Lead Field
    
-   
  3. 
-   
    
-    Loading Solution Points + Computing Lead Field
    
-   
  4. 
-   
    
-    Loading Solution Points + Loading & Interpolating Lead Field
    
-   
  5. 
-   
    
-    Loading & Downsampling Solution Points + Computing Lead Field
    
-   
  6. 
-   
    
-    Loading & Downsampling Solution Points + Loading & 
-    Downsampling Lead Field
    
-   

-  

-    

-  

-   Interpolating a Lead Field

-  

-   A Lead Field (in our case) is discrete
-    vectorial field. As such we are entitled to interpolate from 
-   the known positions & values to get the vectorial values at other
-    positions, allowing us to switch to different solution space distributions.

-  

-   There is a strong constraint however: the new targetted solution 
-   space should be entirely contained within the source solution space.
-    This is the only way to correctly interpolate from known 
-   values, as otherwise we would extrapolate them, which is quite 
-   a risky move for a Lead Field.

-  

-   Interpolation of the vectorial field is currently tri-linear, hence 
-   each target position should have all of the 8 surrounding cube's 
-   neighbors around it.

-  

-   Since Cartool tries to be nice with you, points that are not within 
-   the input solution space will be kept but neutralized
-    for all forthcoming calculations.

-  

-    

-  

-   See here is a correct example of a target solution space, where all 
-   points fit well within the original space:

-  
    
-   
    
-    
    
-   

-  

-    

-  

-   And here is a bad example, where some of the targetted points lie 
-   outside the original space, and will be neutralized:

-  
    
-   
    
-    
    
-   

-  

-    

-  

-   Downsampling a Lead Field

-  

-   When the loaded solution space appear to be too dense for the 
-   inversion in Cartool, the recommended step is to simply downsample it.

-  

-   See here an example of (some heavy) downsampling:

-  
    
-   
    
-    
    
-   

-  

-    

-  

-   Neutralizing some solution points

-  

-   Some solution points might happen to be unfit at some stages of 
-   the inversion, for various reasons. Should this happen, these 
-   points will be "neutralized" for the remaining calculations.

-  

-    

-  

-   Here is a list of some possible reasons to neutralize some points:

-  
    
-   
  • 
-   
    
-    Not enough neighbors (8) for a proper interpolation, when switching
-     from one solution space to another.
    
-   
  • 
-   
    
-    Points without neighbors in the LORETA and LAURA inversions.
    
-   
  • 
-   
    
-    Points with an associated null Lead Field column, when 
-    re-loading a Lead Field with previously neutralized Solution Points.
    
-   

-  

-    

-  

-   Neutralization is quite straightforward, and is all done internally 
-   in Cartool without the need of any user input:

-  
    
-   
  • 
-   
    
-    Points marked as to be neutralized are first removed from the 
-    list of points;
    
-   
  • 
-   
    
-    Cartool will work internally with this restricted list of points, 
-    proceeding with computing all things like Lead Field and inverse
-     matrices;
    
-   
  • 
-   
    
-    Finally, the points that have been removed are inserted back 
-    into the list of points, and the corresponding Lead Field columns 
-    and inverse matrices rows are subsequently filled with 0's.
    
-   

-  

-    

-  

-   This way, the final results will fit exactly into the user's intended 
-   solution space, without the problematic points interfering with the 
-   sensitive computation parts.

-  

-   Currently, the user is not warned during the processing, even with 
-   the Interactive mode, but the verbose
-    file will list if any points that have been neutralized, and for 
-   which reason.

-  

-    

-  

-   Example of neutralized SPs, being too much on the outer side and 
-   therefore lacking enough neighbors for a correct interpolation:

-  
    
-   
    
-    
    
-   

-  

-    

-  

-   Matrix inversion

-  

-    

-  

-   The matrix inversion step

-   Matrix inversion input
Types of inversions

-  
-  

-   Matrix inversion - Technical points

-  
-  

-   Matrix inversion results

-   Final words...

-  

-    

-  

-   The matrix inversion step

-  

-   This is the step where the Lead 
-   Field matrix, which gives the relationship from Solution 
-   Points to electrodes, is mathematically inverted, hence giving the 
-   relationship from electrodes to Solution Points.

-  

-   All the theory and background you need to know are in these books
-    and articles. Yes, read them.

-  

-    

-  

-   Matrix inversion input

-  

-   Either possibilities:

-  
-  

-    

-  

-   Types of inversions

-  

-   Cartool lets you choose which inverse model to use, non-exclusively, 
-   among the following ones. The specific math for each inverse is well 
-   explained in the articles cited below, and will not be replicated here.

-  

-   Note that we usually work with the LORETA or LAURA inverses most of the time.

-  

-    

-  

-   MN

-  

-   The Minimum Norm inverse is the corner-stone of many other inverses, 
-   which are based on top of it. It is available for the sake of benchmarks and 
-   comparisions.

-  

-    

-  

-   One reference among others, with pointers to more literature, is:
"Interpreting Magnetic Fields of the Brain Minimum Norm Estimates",
+         

+              
+         

+         

+             Loading the Lead Field from file
+         

+         

+             The Lead Field (aka Forward model) can be reloaded from an 
+                 external
+                 file
+             . The main reasons could be:
+         

+         
    
+             
  • 
+                 
    
+                     You computed a LF with another model (like BEM
+                     or FEM), and want to plug it into the inversion step of Cartool,
+                 
    
+             
  • 
+                 
    
+                     Or you just want to re-use the LF computed by an earlier run of Cartool,
+                     hence saving time.
+                 
    
+         

+         

+              
+         

+         

+             See this paragraph about 
+                 all
+                 combinations of Solution Points / Lead Field options
+             .
+         

+         

+              
+         

+         

+             Loading Lead Field - Input files
+         

+         

+             You need two input files:
+         

+         
+         

+              
+         

+         

+             Lead Field results
+         

+         

+             Only if you have computed the LF,
+             you'll have the following results:
+         

+         
    
+             
  • 
+                 
    
+                     Some boundary files,
+                 
    
+             
  • 
+                 
    
+                     The  .lf 
+                     Lead Field matrix that can be re-used for later computations (technically
+                     saved as double precision).
+                 
    
+             
  • 
+                 
    
+                     The .ris file also
+                     contains a copy of the Lead Field, which can be used both for display
+                     and for later reloading (saved as single precision).
+                 
    
+             
  • 
+                 
    
+                     For display purpose only, the Lead Field matrix converted into an 
+                         
+                             .sef
+                         
+                     
+                     file. It can be used to display as a map how each SP influences all electrodes.
+                 
    
+                 
    
+                     It only holds the norm of the vectorial Lead Field, per SP, once transposed.
+                 
    
+             
  • 
+                 
    
+                     The .vrb verbose
+                     file contains some detailed results from the optional 
+                         radii
+                         from skull computation
+                      (scalp and skull radii and thicknesses).
+                 
    
+         

+         

+              
+         

+         

+             Solution Points and Lead Field cases
+         

+         

+             
+                 All combinations of Solution Points and
+                 Lead Field cases
+             
Interpolating a Lead Field

+             Downsampling a Lead Field

+             Neutralizing some solution points
+         

+         

+             All combinations of Solution Points and
+             Lead Field cases
+         

+         

+             Cartool allows all possible combinations between 
+                 computing /
+                 loading Solution Points
+             , and computing / loading Lead Field.
+             Here is a table to sort out all these cases and explain their
+             meaning and consequences:
+         

+         

+              
+         

+         
+         

+              
+         

+         

+             Here are also the recommended scenarios, by decreasing order of
+             results quality:
+         

+         
    
+             
  1. 
+                 
    
+                     Computing Solution Points + Computing Lead Field
+                 
    
+             
  2. 
+                 
    
+                     Computing Solution Points + Loading & Interpolating Lead Field
+                 
    
+             
  3. 
+                 
    
+                     Loading Solution Points + Computing Lead Field
+                 
    
+             
  4. 
+                 
    
+                     Loading Solution Points + Loading & Interpolating Lead Field
+                 
    
+             
  5. 
+                 
    
+                     Loading & Downsampling Solution Points + Computing Lead Field
+                 
    
+             
  6. 
+                 
    
+                     Loading & Downsampling Solution Points + Loading &
+                     Downsampling Lead Field
+                 
    
+         

+         

+              
+         

+         

+             Interpolating a Lead Field
+         

+         

+             A Lead Field (in our case) is 
+                 
+                     discrete
+                     vectorial field
+                 
+             . As such we are entitled to interpolate from
+             the known positions & values to get the vectorial values at 
+                 other
+                 positions
+             , allowing us to switch to different solution space distributions.
+         

+         

+             There is a strong constraint however: the 
+                 new targetted solution
+                 space should be entirely contained within the source solution space
+             .
+             This is the only way to correctly interpolate from known
+             values, as otherwise we would extrapolate them, which is quite
+             a risky move for a Lead Field.
+         

+         

+             Interpolation of the vectorial field is currently tri-linear, hence
+             each target position should have all of the 8 surrounding cube's
+             neighbors around it.
+         

+         

+             Since Cartool tries to be nice with you, points that are not within
+             the input solution space will be kept but 
+                 neutralized
+                 for all forthcoming calculations
+             .
+         

+         

+              
+         

+         

+             See here is a correct example of a target solution space, where all
+             points fit well within the original space:
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+              
+         

+         

+             And here is a bad example, where some of the targetted points lie
+             outside the original space, and will be neutralized:
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+              
+         

+         

+             Downsampling a Lead Field
+         

+         

+             When the loaded solution space appear to be too dense for the
+             inversion in Cartool, the recommended step is to simply downsample it.
+         

+         

+             See here an example of (some heavy) downsampling:
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+              
+         

+         

+             Neutralizing some solution points
+         

+         

+             Some solution points might happen to be 
+                 unfit at some stages of
+                 the inversion
+             , for various reasons. Should this happen, these
+             points will be "neutralized" for the remaining calculations.
+         

+         

+              
+         

+         

+             Here is a list of some possible reasons to neutralize some points:
+         

+         
    
+             
  • 
+                 
    
+                     Not enough neighbors (8) for a proper interpolation, when 
+                         switching
+                         from one solution space to another
+                     .
+                 
    
+             
  • 
+                 
    
+                     Points without neighbors in the LORETA and LAURA inversions.
+                 
    
+             
  • 
+                 
    
+                     Points with an associated null Lead Field column, when
+                     re-loading a Lead Field with previously neutralized Solution Points.
+                 
    
+         

+         

+              
+         

+         

+             Neutralization is quite straightforward, and is all done internally
+             in Cartool without the need of any user input:
+         

+         
    
+             
  • 
+                 
    
+                     Points marked as to be neutralized are first removed from the
+                     list of points;
+                 
    
+             
  • 
+                 
    
+                     Cartool will work internally with this restricted list of points,
+                     proceeding with computing all things like Lead Field and 
+                         inverse
+                         matrices
+                     ;
+                 
    
+             
  • 
+                 
    
+                     Finally, the points that have been removed are inserted back
+                     into the list of points, and the corresponding Lead Field columns
+                     and inverse matrices rows are subsequently filled with 0's.
+                 
    
+         

+         

+              
+         

+         

+             This way, the final results will fit exactly into the user's intended
+             solution space, without the problematic points interfering with the
+             sensitive computation parts.
+         

+         

+             Currently, the user is not warned during the processing, even with
+             the Interactive mode, but the 
+                 verbose
+                 file
+              will list if any points that have been neutralized, and for
+             which reason.
+         

+         

+              
+         

+         

+             Example of neutralized SPs, being too much on the outer side and
+             therefore lacking enough neighbors for a correct interpolation:
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+              
+         

+         

+             Matrix inversion
+         

+         

+              
+         

+         

+             The matrix inversion step

+             Matrix inversion input
Types of inversions
+         

+         
+         

+             Matrix inversion - Technical points
+         

+         
+         

+             Matrix inversion results

+             Final words...
+         

+         

+              
+         

+         

+             The matrix inversion step
+         

+         

+             This is the step where the 
+                 
+                     Lead
+                     Field matrix
+                 
+             , which gives the relationship 
+                 from Solution
+                 Points to electrodes
+             , is mathematically inverted, hence giving the
+             relationship from electrodes to Solution Points.
+         

+         

+             All the theory and background you need to know are in these 
+                 
+                     books
+                     and articles
+                 
+             . Yes, read them.
+         

+         

+              
+         

+         

+             Matrix inversion input
+         

+         

+             Either possibilities:
+         

+         
+         

+              
+         

+         

+             Types of inversions
+         

+         

+             Cartool lets you choose which inverse model to use, non-exclusively,
+             among the following ones. The specific math for each inverse is well
+             explained in the articles cited below, and will not be replicated here.
+         

+         

+             Note that we usually work with the LORETA or LAURA inverses most of the time.
+         

+         

+              
+         

+         

+             MN
+         

+         

+             The Minimum Norm inverse is the corner-stone of many other inverses,
+             which are based on top of it. It is available for the sake of benchmarks and
+             comparisions.
+         

+         

+              
+         

+         

+             One reference among others, with pointers to more literature, is:
+         
"Interpreting Magnetic Fields of the Brain Minimum Norm Estimates",
 M. S. Hämäläinen, R. J. Ilmoniemi,
 Med. & Biol. Eng. Comput.,  1994

-  

-   WMN

-  

-   The Weighted Minimum Norm is an improvement to the simple Minimum Norm 
-   above. It works by weighting the inverse results according to the depth of 
-   each solution points, deeper sources being given greater weights. LORETA and 
-   LAURA are also both based on it.

-  

-    

-  

-   You can find some resources for the WMN inverse here:
"Review of Methods for Solving the EEG Inverse Problem",
Roberto Domingo Pascual-Marqui,
International Journal of Bioelectromagnetism, 1999, Vol. 1 N° 1.
 
 
"Electrical neuroimaging base on biophysical constraints",
Rolando Grave de Peralta Menendez, Micah M. Murray, Christoph M. Michel, Roberto Martuzzi, Sara L. Gonzalez Andino,
NeuroImage, 2003.
 
 
http://www.uzh.ch/keyinst/NewLORETA/SomePapers/LORETAcve/01-Reply.htm

-  

-   sDale

-  

-   This is one interpretation of the Dale way of correcting the Minimum Norm 
-   results. It uses the diagonal of the covariance matrix of the sensors to 
-   "recalibrate" the estimated dipoles. The Cartool version is one 
-   possible implementation, the one explained in the sLORETA paper 
-   (hence the name sDale given here). Another version is the dSPM 
-   implementation, which uses a direct estimate of the covariance from 
-   the data. So sDale and dSPM are rather siblings than twins!

-  

-    

-  

-   Here are some references:
"Improved localization of cortical activity by combining EEG and MEG with MRI cortical surface reconstruction A linear approach",
+         

+             WMN
+         

+         

+             The Weighted Minimum Norm is an improvement to the simple Minimum Norm
+             above. It works by weighting the inverse results according to the depth of
+             each solution points, deeper sources being given greater weights. LORETA and
+             LAURA are also both based on it.
+         

+         

+              
+         

+         

+             You can find some resources for the WMN inverse here:
+         
"Review of Methods for Solving the EEG Inverse Problem",
Roberto Domingo Pascual-Marqui,
International Journal of Bioelectromagnetism, 1999, Vol. 1 N° 1.
 
 
"Electrical neuroimaging base on biophysical constraints",
Rolando Grave de Peralta Menendez, Micah M. Murray, Christoph M. Michel, Roberto Martuzzi, Sara L. Gonzalez Andino,
NeuroImage, 2003.
 
 
http://www.uzh.ch/keyinst/NewLORETA/SomePapers/LORETAcve/01-Reply.htm

+         

+             sDale
+         

+         

+             This is one interpretation of the Dale way of correcting the Minimum Norm
+             results. It uses the diagonal of the covariance matrix of the sensors to
+             "recalibrate" the estimated dipoles. The Cartool version is 
+                 one
+                 possible implementation
+             , the one explained in the sLORETA paper
+             (hence the name sDale given here). 
+                 Another version is the dSPM
+                 implementation
+             , which uses a direct estimate of the covariance 
+                 from
+                 the data
+             . So sDale and dSPM are rather siblings than twins!
+         

+         

+              
+         

+         

+             Here are some references:
+         
"Improved localization of cortical activity by combining EEG and MEG with MRI cortical surface reconstruction A linear approach",
 Dale Sereno,
 J. of Cogn. Neurosc., 1993
 
@@ -3243,236 +4509,343 @@ 

 "Standardized low resolution brain electromagnetic tomography (sLORETA): technical details",
 R.D. Pascaul-Marqui,
 Methods & Findings in Experimental & Clinical Pharmacology, 2002

-  

-   sLORETA

-  

-   This version of the Minimum Norm adds a final standardization step estimated 
-   from the noise, an approach very close to the one of Dale. 
-   Also note that it has nothing in common with LORETA, apart from being based 
-   on the MN and its author personnal interest in this very name...

-  

-    

-  

-   The original paper about sLORETA:
"Standardized low resolution brain electromagnetic tomography (sLORETA): technical details",
+         

+             sLORETA
+         

+         

+             This version of the Minimum Norm adds a final standardization step estimated
+             from the noise, an approach very close to the one of Dale.
+             Also note that it has nothing in common with LORETA, apart from being based
+             on the MN and its author personnal interest in this very name...
+         

+         

+              
+         

+         

+             The original paper about sLORETA:
+         
"Standardized low resolution brain electromagnetic tomography (sLORETA): technical details",
 R.D. Pascaul-Marqui,
 Methods & Findings in Experimental & Clinical Pharmacology, 2002

-  

-   LORETA

-  

-   LORETA is based on the WMN inverse, and adds a Laplacian to ensure 
-   some local smoothness in the inverse. Somehow, this also seems to make it the 
-   most robust to noise. A quite good and general purpose inverse!

-  

-    

-  

-   You can find some resources for the LORETA inverse here:
Electrical Neuroimaging,
Chr. Michel, Th. Koenig, D. Brandeis, L.R.R. Gianotti and J. Wackermann,
Cambridge University Press, 2009.
 
 
Review of Methods for Solving the EEG Inverse Problem,
Roberto Domingo Pascual-Marqui,
International Journal of Bioelectromagnetism, 1999, Vol. 1, N° 1.
 
 
Electrical neuroimaging base on biophysical constraints,
Rolando Grave de Peralta Menendez, Micah M. Murray, Christoph M. Michel, Roberto Martuzzi, Sara L. Gonzalez Andino,
NeuroImage, 2003.
 
 
http://www.uzh.ch/keyinst/NewLORETA/SomePapers/LORETAcve/01-Reply.htm

-  

-   LAURA

-  

-   The LAURA inverse is also based on the WMN inverse, and is very close to the LORETA 
-   inverse. It replaces the Laplacian used for smoothness with another local 
-   auto-regressive operator (plus, it sounds impressive). Results are also quite 
-   robust to noise.

-  

-    

-  

-   You can find some resources for the LAURA inverse here:
Electrical Neuroimaging,
Chr. Michel, Th. Koenig, D. Brandeis, L.R.R. Gianotti and J. Wackermann,
Cambridge University Press, 2009.
 
 
Electrical neuroimaging base on biophysical constraints,
Rolando Grave de Peralta Menendez, Micah M. Murray, Christoph M. Michel, Roberto Martuzzi, Sara L. Gonzalez Andino,
NeuroImage, 2003.
 
 
Comparison of Algorithms for the Localization of Focal Sources: Evaluation with simulated data
and analysis of experimental data,
Rolando Grave de Peralta Menendez, Sara L. Gonzalez Andino,
International Journal of Bioelectromagnetism, 2002, Vol., 4 N° 1.

-  

-   eLORETA

-  

-   The latest avatar of the LORETA family, still based on MN inverse. It has the 
-   very nice property of an exact localization for 1 single dipole and
-   no noise. However it degrades pretty fast for even small 
-   amount of noise (10%), and also if more than one source is present. Still an 
-   interesting inverse to have. And again, it has nothing to do with the 
-   historically first LORETA inverse, and neither with sLORETA... Think about 
-   other names at one point, maybe?

-  

-    

-  

-   eLORETA original description is only available as a non-peer reviewed 
-   technical paper, here:
"Discrete, 3D distributed linear imaging methods of electric neuronal activity. Part 1: exact, zero error localization",
+         

+             LORETA
+         

+         

+             LORETA is based on the WMN inverse, and adds a Laplacian to ensure
+             some local smoothness in the inverse. Somehow, this also seems to make it the
+             most robust to noise. A quite good and general purpose inverse!
+         

+         

+              
+         

+         

+             You can find some resources for the LORETA inverse here:
+         
Electrical Neuroimaging,
Chr. Michel, Th. Koenig, D. Brandeis, L.R.R. Gianotti and J. Wackermann,
Cambridge University Press, 2009.
 
 
Review of Methods for Solving the EEG Inverse Problem,
Roberto Domingo Pascual-Marqui,
International Journal of Bioelectromagnetism, 1999, Vol. 1, N° 1.
 
 
Electrical neuroimaging base on biophysical constraints,
Rolando Grave de Peralta Menendez, Micah M. Murray, Christoph M. Michel, Roberto Martuzzi, Sara L. Gonzalez Andino,
NeuroImage, 2003.
 
 
http://www.uzh.ch/keyinst/NewLORETA/SomePapers/LORETAcve/01-Reply.htm

+         

+             LAURA
+         

+         

+             The LAURA inverse is also based on the WMN inverse, and is very close to the LORETA
+             inverse. It replaces the Laplacian used for smoothness with another local
+             auto-regressive operator (plus, it sounds impressive). Results are also quite
+             robust to noise.
+         

+         

+              
+         

+         

+             You can find some resources for the LAURA inverse here:
+         
Electrical Neuroimaging,
Chr. Michel, Th. Koenig, D. Brandeis, L.R.R. Gianotti and J. Wackermann,
Cambridge University Press, 2009.
 
 
Electrical neuroimaging base on biophysical constraints,
Rolando Grave de Peralta Menendez, Micah M. Murray, Christoph M. Michel, Roberto Martuzzi, Sara L. Gonzalez Andino,
NeuroImage, 2003.
 
 
Comparison of Algorithms for the Localization of Focal Sources: Evaluation with simulated data
and analysis of experimental data,
Rolando Grave de Peralta Menendez, Sara L. Gonzalez Andino,
International Journal of Bioelectromagnetism, 2002, Vol., 4 N° 1.

+         

+             eLORETA
+         

+         

+             The latest avatar of the LORETA family, still based on MN inverse. It has the
+             very nice property of an exact localization for 
+                 1 single dipole and
+                 no noise
+             . However it degrades pretty fast for even small
+             amount of noise (10%), and also if more than one source is present. Still an
+             interesting inverse to have. And again, it has nothing to do with the
+             historically first LORETA inverse, and neither with sLORETA... Think about
+             other names at one point, maybe?
+         

+         

+              
+         

+         

+             eLORETA original description is only available as a non-peer reviewed
+             technical paper, here:
+         
"Discrete, 3D distributed linear imaging methods of electric neuronal activity. Part 1: exact, zero error localization",
 Pascual-Marqui,
 Technical Report, arXiv 2007

-  

-    

-  

-   Matrix inversion - Technical points

-  

-   Tikhonov regularization

-  

-   Some regularization has to be used if there is any sort of noise
-    in the data, which is always the case with real-life data:

-  
    
-   
    
-    
    
-   
    
-    (with K being the Lead Field, W the specific weights of 
-    the inverse,  
-    the regularization factor, J the current source density,  
-    the surface potential)
    
-   

-  

-    

-  

-   One problem arises from the fact that the regularization factor  
-   depends on:

-  
    
-   
  • 
-   
    
-    The type of inverse (LORETA, LAURA, etc...)
    
-   
  • 
-   
    
-    The noise level of the data.
    
-   

-  

-   The latter is not always know in advance, and even so, we don't want 
-   to compute an inverse matrix that couldn't be used with other data sets!

-  

-    

-  

-   The solution for Cartool is to compute a set of matrices with 
-   a range of 's,
-    from which the user can later
-    select:

-  
    
-   
  • 
-   
    
-    For a given inverse model, first compute the constant Eigen
    
-   
    
-    
    
-   
  • 
-   
    
-    Then for i=0 to 12, use the following regularization factors i
    
-   
    
-    
    
-   

-  

-    

-  

-   You end up with 13 matrices (for each type of inverse, of 
-   course), the first one without regularization, and the following 12 
-   ones with linearly increasing levels of regularization.

-  

-    

-  

-   Stack of inverse matrices

-  

-   Linked to the point above, we 
-   currently output 13 matrices per inverse type (LORETA, LAURA, 
-   etc...). However, this could be rather clumsy and error prone to 
-   manipulate as separate files.

-  

-    

-  

-   To ease a bit your life, Cartool has upgraded the .is 
-   format so as to be able to pack a set of matrices into a single
-    file. This "super-matrix" offers the following advantages:

-  
    
-   
  • 
-   
    
-    easier to copy/delete/drop,
    
-   
  • 
-   
    
-    no regularization can be lost by itself,
    
-   
  • 
-   
    
-    all the regularizations can be browsed at once, f.ex. for an 
-    automated search 
-    of an optimal regularization.
    
-   

-  

-    

-  

-   Neighborhood connectivity

-  

-   Within the Cartool implementation, both LORETA and LAURA inverses use an
-    average of 18 neighbors, needed to compute the Laplacian (f.ex.).

-  

-   For each Solution Point, voxels from the 18
-    neighbors are first taken, and if there aren't enough of 
-   them, then the 26 neighbors. This way, all the Solution Points 
-   are closer to 18 neighbors in average.

-  

-    

-  

-   The results of inverse section provides 
-   some details about the resulting neighborhood: the connectivity 
-   between SPs, and the actual density of neighbors per SP.

-  

-    

-  

-   Matrix inversion results

-  

-   These are the final results for the Inverse Solutions:

-  
    
-   
  • 
-   
    
-    The much desired  .is 
-     Inverse matrix file(s) (see this note).
    
-      
  • 
-      
    
-    The .vrb verbose 
-    file contains some detailed results, like statistics about neighborhood.
    
-   

-  

-    

-  

-   Final words...

-  

-   You can now use your shiny new inverse matrices for some interactive
-    display, or to perform the last step by 
-   multiplying them by 
-   the EEG.

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    
+         

+              
+         

+         

+             Matrix inversion - Technical points
+         

+         

+             Tikhonov regularization
+         

+         

+             Some regularization has to be used if there is any sort of 
+                 noise
+                 in the data
+             , which is always the case with real-life data:
+         

+         
    
+             
    
+                 
+             
    
+             
    
+                 (with K being the Lead Field, W the specific weights of
+                 the inverse, 
+                 the regularization factor, J the current source density, 
+                 the surface potential)
+             
    
+         

+         

+              
+         

+         

+             One problem arises from the fact that the regularization factor 
+             depends on:
+         

+         
    
+             
  • 
+                 
    
+                     The type of inverse (LORETA, LAURA, etc...)
+                 
    
+             
  • 
+                 
    
+                     The noise level of the data.
+                 
    
+         

+         

+             The latter is not always know in advance, and even so, we don't want
+             to compute an inverse matrix that couldn't be used with other data sets!
+         

+         

+              
+         

+         

+             The solution for Cartool is to compute a set of matrices with
+             a range of 's,
+             from which the user can 
+                 later
+                 select
+             :
+         

+         
    
+             
  • 
+                 
    
+                     For a given inverse model, first compute the constant Eigen
+                 
    
+                 
    
+                     
+                 
    
+             
  • 
+                 
    
+                     Then for i=0 to 12, use the following regularization factors i
+                 
    
+                 
    
+                     
+                 
    
+         

+         

+              
+         

+         

+             You end up with 13 matrices (for each type of inverse, of
+             course), the first one without regularization, and the following 12
+             ones with linearly increasing levels of regularization.
+         

+         

+              
+         

+         

+             Stack of inverse matrices
+         

+         

+             Linked to the point above, we
+             currently output 13 matrices per inverse type (LORETA, LAURA,
+             etc...). However, this could be rather clumsy and error prone to
+             manipulate as separate files.
+         

+         

+              
+         

+         

+             To ease a bit your life, Cartool has upgraded the .is
+             format so as to be able to pack a set of matrices into a 
+                 single
+                 file
+             . This "super-matrix" offers the following advantages:
+         

+         
    
+             
  • 
+                 
    
+                     easier to copy/delete/drop,
+                 
    
+             
  • 
+                 
    
+                     no regularization can be lost by itself,
+                 
    
+             
  • 
+                 
    
+                     all the regularizations can be browsed at once, f.ex. for an
+                     automated 
+                         
+                             search
+                             of an optimal regularization
+                         
+                     .
+                 
    
+         

+         

+              
+         

+         

+             Neighborhood connectivity
+         

+         

+             Within the Cartool implementation, both LORETA and LAURA inverses use 
+                 an
+                 average of 18 neighbors
+             , needed to compute the Laplacian (f.ex.).
+         

+         

+             For each Solution Point, voxels from the 
+                 
+                     18
+                     neighbors
+                 
+              are first taken, and if there aren't enough of
+             them, then the 26 neighbors. This way, all the Solution Points
+             are closer to 18 neighbors in average.
+         

+         

+              
+         

+         

+             The results of inverse section provides
+             some details about the resulting neighborhood: the connectivity
+             between SPs, and the actual density of neighbors per SP.
+         

+         

+              
+         

+         

+             Matrix inversion results
+         

+         

+             These are the final results for the Inverse Solutions:
+         

+         
    
+             
  • 
+                 
    
+                     The much desired  .is 
+                     Inverse matrix file(s) (see this note).
+                 
    
+             
  • 
+                 
    
+                     The .vrb verbose
+                     file contains some detailed results, like statistics about neighborhood.
+                 
    
+         

+         

+              
+         

+         

+             Final words...
+         

+         

+             You can now use your shiny new inverse matrices for some 
+                 
+                     interactive
+                     display
+                 
+             , or to perform the last step by 
+                 
+                     multiplying them by
+                     the EEG
+                 
+             .
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+     

  
 
\ No newline at end of file
diff --git a/docs/ReferenceGuide/computing-ris.html b/docs/ReferenceGuide/computing-ris.html
index 3f394c34..ecde79e3 100644
--- a/docs/ReferenceGuide/computing-ris.html
+++ b/docs/ReferenceGuide/computing-ris.html
@@ -37,709 +37,989 @@
 
  
 
- 
-  

-   Computing Results of Inverse Solution

-  

-    

-  

-   Once the Inverse Matrix has 
-   been computed, you can apply it to EEG or 
-   Frequency data, and 
-   obtain some .ris 
-   files (results of inverse solution). 
-   These  .ris 
-   files can subsequently be used  
-   for display, 
-   
-   for statistics, or even 
-   converted to volumes for fMRI 
-   comparison.

-  
Here is a highly recommended article about practical use of the inverse 
-  solutions:

-  
"EEG Source Imaging: A Practical Review of the Analysis Steps",
+ 
+     

+         

+             Computing Results of Inverse Solution
+         

+         

+              
+         

+         

+             Once the 
+                 
+                     Inverse Matrix has
+                     been computed
+                 
+             , you can apply it to EEG or
+             Frequency data, and
+             obtain some 
+                 .ris
+                 files
+              (results of inverse solution).
+             These  
+                 .ris
+                 files
+              can subsequently be used 
+                 for display
+             ,
+             
+                 
+                     for statistics
+                 
+             , or even 
+                 converted to volumes
+              for fMRI
+             comparison.
+         

+         

+             Here is a highly recommended article about practical use of the inverse
+             solutions:
+         

+         
"EEG Source Imaging: A Practical Review of the Analysis Steps",
 C.M. Michel, D. Brunet,
 Front. Neurol., 04 April 2019

-  

-   Computing RIS Dialog

-  

-   Technical points & hints

-  

-   Checking the files consistency

-  

-   Spatial Filter

-  

-   Background normalization

-  

-   Templatize results

-  

-   Frequency files

-  

-   Results

-  

-   Computing RIS Dialog

-  

-   Called from the Tools
-    | Inverse Solutions | Computing Results of Inverse Solutions menu, the following dialog 
-   appears:

-  

-   Computing RIS Dialog

-  

-    

-   
-       
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-       
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-       
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-       
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-       
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-   

-      

-       Presets

-      

-       You can quickly set the most important parameters according to some 
-	   predefined scenarios. You are then free to fine-tune any parameter, of 
-	   course.

-      

-       (1) Groups of EEG Files

-      

-        
One Group of Files Contains:
-      

-       Use this preset to specify how Cartool has to understand each group of 
-	   files that you give it:

-	 
    
-		 
  • All Subjects, One Condition: a group of files holds all subjects at 
-		 once, for 1 condition only
    • 
-		 
  • 1 Subject, All Conditions: a group of files holds only 1 subvject, 
-		 and all conditions together
    • 
-		 
  • 1 Subject, All Epochs and All Conditions: drop all epochs, all 
-		 conditions for a single subject
    • 
-	 

-      

-       You can still change the preset even after the files have been dropped 
-	   in.

-      

-       Add New Group of Files

-      

-       Enter a new group EEG or 
-	   Frequency files.

-       Cartool will check that the new group of 
-	   files is compatible with the existing ones, and will complain if 
-	   needed...

-      

-       Remove Last Group

-      

-       Does what it says.

-      

-       Clear All Groups

-      

-       Clear out all the groups at once.

-      

-       Read Lists from File

-      

-       You can direclty retrieve the lists of groups previously (see below).

-      

-       See also Drag & Drop.

-      

-       Write Lists to File

-      

-       You can save the lists of current groups into a file, in case you 
-       want to re-use them (much recommended!).

-      

-       See the file formats available.

-      

-       (List of current groups of files)

-      

-       For your entertainment and great pleasure, you can here contemplate your 
-	   life and a summary of all the groups of files you already added to this 
-	   sub-box.

-      

-       Number of Subjects:

-       Number of conditions:

-      

-       A summary of what Cartool understands in terms of subjects and 
-	   conditions.

-      

-       (2) EEG Preprocessing

-      

-        

-      

-       EEG Spatial Filter, using XYZ file:

-      

-       If this option is selected, then the EEG data will be 
-	   preprocessed with a 
-	   Spatial Filter.

-       This filter takes care of any remaining outliers, while also smoothing 
-	   out the data. This really improves the Results of Inverse Solution, 
-	   as outliers are definitely a no-no.

-       Cartool will check that electrodes 
-	   coordinates is compatible with the other files, and will complain if 
-	   needed...

-      

-       (3) Inverse Processing

-      

-        

-      

-       Inverse Matrix File:

-      

-       This one input is mandatory, so give one of the
-	   inverse matrix generated here.

-       Cartool will check that inverse matrix is 
-	   compatible with the other files, and will complain if needed...

-      

-       Results Type:

-      
The type of results to be actually saved.
Inverse solutions produces 
-	  dipoles for each solution points, each dipole therefor coding for both 
-	  orientation and power. You can specify what to do with these vecotrial 
-	  information.

-      

-       Norm

-      

-       Only the norm of each dipole will be saved.

-       This is what you need 99% of the time.

-      

-       Vectorial

-      

-       The complete vector of each dipole will be saved.

-       Not recommended unless you know what you are doing. Also, it 
-	   takes more space on the disk.

-      

-       Inverse Regularization:

-      

-       
-	   Regularization is a kind of smoothing that accounts for noise 
-	   in the data.

-       Apply more regularization for noisier data, and less for cleaner data.

-       Don't over-do regularization, as makes the localization more blurry and less precise.

-	 

-       Auto

-      

-       Data is tested against all available regularizations. 
-	   Then the optimal one is picked: the lowest regularization factor that 
-	   doesn't change much the results.

-       This is the 
-		  recommended option.

-	 

-       Fixed

-      

-       Or you can set a specific regularization factor, ranging 
-	   from 0 (none) to 12 (max), 4 being the 
-	   default value.

-      

-       (4) Inverse Postprocessing

-      

-        

-      

-       Standardize Solution Points (in 
-	   Time):

-      

-       This will normalize the time course of each solution point 
-	   by its background activity (noise). The real activities, 
-	   the highest values, are not taken into account 
-	   in the formula, as this would be counter-productive by 'neutralizing' 
-	   them.

-       This option is highly recommened for optimal results!

-       See the relevant discussion here.

-      

-       Compute Z-Score

-      

-       Compute the Z-Scores every time.

-      

-       Load Z-Score factors files

-      

-       Try to reload the Z-Score factors from existing files. Files should match 
-	   the inverse name and regularization, and of course, subjects' names.

-      

-       Templatize (per Map):

-      

-       Apply some sort of normalization to output only templates of 
-	   activations, stripping the power component out.

-      

-       Ranking

-      

-       Each sample's results will be ranked, for each sample 
-	   independently. Hence values will be between (0..1]

-      

-       Envelope (Gap Bridging, in Time):

-      

-       Apply an Envelope method ("Gap Bridging") to the norms of results. This 
-	   goes faster than Hilbert transform, and gives more or less consistent 
-	   results.

-      

-       Lowest Band-Pass Frequency:

-      

-       Provide here the lowest frequency to account for for the envelope.

-      

-       ROIs (per Map):

-      

-       If the option is selected, you have to provide the ROIs file that matches 
-	   the current inverse matrix.

-       This is useful to reduce the results'size. It is of course applied for 
-	   each sample at a time.

-       ROIs results are computed using a Median, not 
-	   a Mean, of all points belonging to a given region.

-       Cartool will check that ROIs are compatible 
-	   with the other files, and will complain if needed...

-      

-       (4) Output Options

-      

-        

-      

-       Optional Base File Name Prefix:

-      

-       Specify here an optional prefix for all the output file names.

-      

-       Saving Files:

-      

-       A few options to tailor how you want to overflow your disk with files...

-      

-       Every Subjects' RIS

-      

-       Each input file will have a one-to-one corresponding output 
-	   .ris 
-	   file.

-      

-       + Every Epochs' RIS

-      

-       All Epochs will have a corresponding  
-	   .ris 
-	   file, which means, that could be huge.

-      

-       Computing Grand Averages

-      

-       This option, usually associated with ERP experiments, will gracefully 
-	   compute the average .ris 
-	   of each condition.

-       It will work correctly only if all the files have exactly the same 
-	   lengths, across all conditions and all subjects.

-      

-       Computing Clusters Centroids

-      

-       This option is tailored for clusters of data (from the Fitting f.ex.). It 
-	   will compute the mean template across each cluster of data. This 
-	   might be even the only results of interest in that specific case...

-      

-       Z-Score Factors

-      

-       Save the Z-Score factors to file. This could be handy in case of 
-	   re-computation by just reloading them - these factors take a bit of time 
-	   to compute...

-      

-       Process

-      

-       Runs the computation.

-      

-       This button remains disabled until all the parameter 
-       dialogs have received enough (and consistent) informations.

-      

-       Cancel

-      

-       Quit the dialog.

-      

-       Help

-      

-       Launch the Help to the right page (should be here...).

-  

-   Computing RIS - Technical points & hints

-  

-   Checking the files consistency

-  

-   Cartool will run your input files through an extensive set of consistency 
-   rules. The purpose being first to avoid crashes, and second to check that you 
-   haven't picked the wrong files.

-  

-   The main consistency checks are the following:

-  
    
-	  
  • Within the same EEG group:
      
-		  
    • Same number of electrodes
      • 
-		  
    • Same sampling frequency
      • 
-		  
    • Same duration, in case or ERPs
      • 
-	  
    
-	  
    • 
-	  
  • Within different subject's groups:
      
-		  
    • Same number of files
      • 
-		  
    • Same duration in case of ERPs
      • 
-	  
    
-	  
    • 
-	  
  • Across EEG, Inverse Matrix and Electrodes Coordinates:
      
-		  
    • Same number of electrodes between the matrix and the EEG
      • 
-		  
    • Same number of electrodes between the Electrodes Coordinates and 
-		  the EEG
      • 
-	  
    
-	  
    • 
-	  
  • Across Inverse Matrix, Solution Points and ROIs:
      
-		  
    • Without ROIs, same number of Solution Points with the Inverse 
-		  Matrix
      • 
-		  
    • With ROIs, same number of Solution Points with the ROIs number of 
-		  regions
      • 
-	  
    
-	  
    • 
-  

-  

-    

-  

-   See here a simplified view of how files are checked, without ROIs:

-  

-   files compatibility checks - no ROIs

-  

-    

-  

-   And here the same view, but with ROIs:

-  

-   files compatibility checks - with ROIs

-  

-   Spatial Filter

-  

-   Applying the Spatial filter is strongly recommended before computing the 
-   results of inverse solutions if there remains any transient artifacts, and/or 
-   data is even slightly noisy. Both degrade the quality of the localization, or can even make 
-   it totally erroneous.

-  

-   The exact specification of the 
-   Spatial Filter is here.

-  

-   The Spatial filter is a non-linear filter that will get rid of local 
-   outliers, while also smoothing the overall map. It will, however, retain the 
-   global aspect of the map's topography. See here an example of before (A) and 
-   after (B) the Spatial filter, on the tracks (left) then on the maps (middle 
-   and right): 

-  

-   spatial filter

-  

-   Background normalization via custom Z-Score

-  

-   Due to various reasons, like an incorrect head geometry, or approximate skull 
-   conductivity, some solution points will show more power than others. 
-   Moreover, these power variations depend on each subject. Therefor, a 
-   normalization step can only be applied after the results of inverse have been 
-   computed, not before.

-  

-   Before stepping into the formula, it is important to get the underlying idea 
-   right. This normalization step will be based solely on the background 
-   / noise activity. The higher values are not used at all, so 
-   to not bias the correction.

-  

-   A custom Z-Score has been tailored to deal with the norm of dipoles. The idea is to convert from 
-   a Chi-square distribution to a Normal 
-   distribution (Equ. 1 and 2), then to a Z-Score (Equ. 3). Finally 
-   data are offsetted by 3 standard deviations so as to remain positive (Equ. 6). The 
-   tricky implementation part is all about estimating the Modes and (left part 
-   of) Median of Absolute Deviation:

-  

-   Z-Score equations for RIS

-  

-   The resulting new solution points values remain positive, as to remain consistent with the original data, 
-   but now with the noise having a Normal distribution centered on 1 (and a SD of 1/3).

-  

-   See here an example of before (left picture) and after (right picture) 
-   standardization, showing the color plot of the histogram (horizontal acis) of 
-   each solution point (vertical axis):

-  

-          
-   

-  

-   Templatize results

-  

-   If one is interested on only having a template of all active brains 
-   regions, and does not care about power in the results, then the 
-   Templatize options come in handy. This is typically used for Micro-tates 
-   analysis f.ex.

-  

-   Ranking will rank, and normalize to 1, every solution 
-   points' results, for each sample / time point independently.

-  

-   An additional Thresholding is available to clear-out 
-   the lowest 90% of the data, hence keeping the top 10%. Indeed, one 
-   never looks at the lowest responses at all, it is mostly noise and/or some 
-   possible inverse artefacts. It could be wise to not account for these!

-  

-    

-  

-   Here is an example of the effect of templatizing the results. Top data are 
-   regulard ERP results, which power vary time. Corresponding inverse on the 
-   right is kind of blurry. Bottom data is ranked + thresholded results, max 
-   values are 1. Corresponding inverse are less blurry, but power information is 
-   gone.

-  

-   

-  

-   Frequency files

-  

-   Noteworthy is the fact that you can input frequency files, 
-   and hence compute the results of inverse solution at different frequencies.

-  

-   Here are the necessary steps to achieve that:

-  
    
-	  
  • When computing the frequency results, use the  
-	  Wavelet for Source Space  preset. It sets the 
-	  output format to be of Complex type, which is mandatory for our 
-	  case here!
    • 
-	  
  • Inverses will be computed at each frequency, separately on the
-	  Real and 
-	  Imaginary parts,
    • 
-	  
  • Then the square of the norm of the Real 
-	  and Imaginary dipoles are 
-	  summed,
    • 
-	  
  • Finally, it is strongly recommended to apply ROIs at 
-	  that stage, to help reduce the size of the final data!
    • 
-  

-  

-    

-  

-   See here, for example, the results at 4 different frequencies, and for all 
-   solution points (no ROIs):

-  

-   

-   

-  

-   Computing RIS - Results

-  
    
-	  
  • For each input file, its corresponding <input file>.ris 
-	  . These files can be directly used for 
-	  display.
    • 
-	  
  • In case of Z-Score option, the Z-Score Mean and SD values in a file 
-	  <output file.ZScoreFactors>.sef  
-	  . The Z-Score file has 2 rows: one for the Mean and one for the Standard 
-	  Deviation, for each solution point.
    • 
-	  
  • Optionally for each group, the Mean of the 
-	  group  <group #.Mean>.ris
    • 
-  

-  

-    

-  

-   Here is an example of ERP, top is the EEG on 204 electrodes, bottom the 
-   transformed ris file. We can note that the EEG data are of course signed 
-   data, more or less in the range -4..4, while the ris data are indeed centered 
-   around 1:

-  

-   before ris

-  

-   after ris

-  

-    

-  

-   And here is an example of a map and its corresponding inverse display:

-  

-   EEG vs RIS display

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  
 

-  
 

+         

+             Computing RIS Dialog
+         

+         

+             Technical points & hints
+         

+         

+             Checking the files consistency
+         

+         

+             Spatial Filter
+         

+         

+             Background normalization
+         

+         

+             Templatize results
+         

+         

+             Frequency files
+         

+         

+             Results
+         

+         

+             Computing RIS Dialog
+         

+         

+             Called from the 
+                 
+                     Tools
+                     | Inverse Solutions | Computing Results of Inverse Solutions
+                 
+              menu, the following dialog
+             appears:
+         

+         

+             Computing RIS Dialog
+         

+         

+              
+         

+         
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+         

+                     

+                         Presets
+                 

+                     

+                         You can quickly set the most important parameters according to some
+                         predefined scenarios. You are then free to fine-tune any parameter, of
+                         course.
+                 

+                     

+                         (1) Groups of EEG Files
+                 

+                     

+                          
+                 
One Group of Files Contains:
+                     

+                         Use this preset to specify how Cartool has to understand each group of
+                         files that you give it:
+                     

+                     
    
+                         
  • 
+                             All Subjects, One Condition: a group of files holds all subjects at
+                             once, for 1 condition only
+                         
    • 
+                         
  • 
+                             1 Subject, All Conditions: a group of files holds only 1 subvject,
+                             and all conditions together
+                         
    • 
+                         
  • 
+                             1 Subject, All Epochs and All Conditions: drop all epochs, all
+                             conditions for a single subject
+                         
    • 
+                     

+                     

+                         You can still change the preset even after the files have been dropped
+                         in.
+                 

+                     

+                         Add New Group of Files
+                 

+                     

+                         Enter a new group EEG or 
+                             Frequency
+                          files.
+                     

+                         
+                             Cartool will check that the new group of
+                             files is compatible
+                          with the existing ones, and will complain if
+                         needed...
+                 

+                     

+                         Remove Last Group
+                 

+                     

+                         Does what it says.
+                 

+                     

+                         Clear All Groups
+                 

+                     

+                         Clear out all the groups at once.
+                 

+                     

+                         Read Lists from File
+                 

+                     

+                         You can direclty retrieve the lists of groups previously (see below).
+                     

+                     

+                         See also Drag & Drop.
+                 

+                     

+                         Write Lists to File
+                 

+                     

+                         You can save the lists of current groups into a file, in case you
+                         want to re-use them (much recommended!).
+                     

+                     

+                         See the file formats available.
+                 

+                     

+                         (List of current groups of files)
+                 

+                     

+                         For your entertainment and great pleasure, you can here contemplate your
+                         life and a summary of all the groups of files you already added to this
+                         sub-box.
+                 

+                     

+                         Number of Subjects:
+                     

+                         Number of conditions:
+                 

+                     

+                         A summary of what Cartool understands in terms of subjects and
+                         conditions.
+                 

+                     

+                         (2) EEG Preprocessing
+                 

+                     

+                          
+                 

+                     

+                         EEG Spatial Filter, using XYZ file:
+                 

+                     

+                         If this option is selected, then the EEG data will be
+                         
+                             
+                                 preprocessed with a
+                                 Spatial Filter
+                             
+                         .
+                     

+                         This filter 
+                             takes care of any remaining outliers, while also smoothing
+                             out the data
+                         . This really improves the Results of Inverse Solution,
+                         as outliers are definitely a no-no.
+                     

+                         
+                             Cartool will check that electrodes
+                             coordinates is compatible
+                          with the other files, and will complain if
+                         needed...
+                 

+                     

+                         (3) Inverse Processing
+                 

+                     

+                          
+                 

+                     

+                         Inverse Matrix File:
+                 

+                     

+                         This one input is mandatory, so give one of the
+                         inverse matrix generated here.
+                     

+                         
+                             Cartool will check that inverse matrix is
+                             compatible
+                          with the other files, and will complain if needed...
+                 

+                     

+                         Results Type:
+                 

+                     
The type of results to be actually saved.

+                         Inverse solutions produces
+                         dipoles for each solution points, each dipole therefor coding for both
+                         orientation and power. You can specify what to do with these vecotrial
+                         information.
+                 

+                     

+                         Norm
+                 

+                     

+                         Only the norm of each dipole will be saved.
+                     

+                         This is what you need 99% of the time.
+                 

+                     

+                         Vectorial
+                 

+                     

+                         The complete vector of each dipole will be saved.
+                     

+                         Not recommended unless you know what you are doing. Also, it
+                         takes more space on the disk.
+                 

+                     

+                         Inverse Regularization:
+                 

+                     

+                         
+                             
+                                 Regularization
+                             
+                          is a kind of smoothing that accounts for noise
+                         in the data.
+                     

+                         Apply more regularization for noisier data, and less for cleaner data.
+                     

+                         Don't over-do regularization, as makes the localization more blurry and less precise.
+                 

+                     

+                         Auto
+                 

+                     

+                         Data is tested against all available regularizations.
+                         Then the optimal one is picked: the lowest regularization factor that
+                         doesn't change much the results.
+                     

+                         
+                             
+                                 This is the
+                                 recommended option
+                             
+                         .
+                 

+                     

+                         Fixed
+                 

+                     

+                         Or you can set a specific regularization factor, ranging
+                         from 0 (none) to 12 (max), 4 being the
+                         default value.
+                 

+                     

+                         (4) Inverse Postprocessing
+                 

+                     

+                          
+                 

+                     

+                         
+                             
+                                 Standardize Solution Points (in
+                                 Time):
+                             
+                         
+                 

+                     

+                         This will normalize the time course of each solution point
+                         by its background activity (noise). The real activities,
+                         the highest values, are not taken into account
+                         in the formula, as this would be counter-productive by 'neutralizing'
+                         them.
+                     

+                         This option is highly recommened for optimal results!
+                     

+                         See the relevant discussion here.
+                 

+                     

+                         Compute Z-Score
+                 

+                     

+                         Compute the Z-Scores every time.
+                 

+                     

+                         Load Z-Score factors files
+                 

+                     

+                         Try to reload the Z-Score factors from existing files. Files should match
+                         the inverse name and regularization, and of course, subjects' names.
+                 

+                     

+                         Templatize (per Map):
+                 

+                     

+                         Apply some sort of normalization to output only 
+                             templates of
+                             activations
+                         , stripping the power component out.
+                 

+                     

+                         Ranking
+                 

+                     

+                         Each sample's results will be ranked, 
+                             for each sample
+                             independently
+                         . Hence values will be between (0..1]
+                 

+                     

+                         Envelope (Gap Bridging, in Time):
+                 

+                     

+                         Apply an Envelope method ("Gap Bridging") to the norms of results. This
+                         goes faster than Hilbert transform, and gives more or less consistent
+                         results.
+                 

+                     

+                         Lowest Band-Pass Frequency:
+                 

+                     

+                         Provide here the lowest frequency to account for for the envelope.
+                 

+                     

+                         ROIs (per Map):
+                 

+                     

+                         If the option is selected, you have to provide the ROIs file that matches
+                         the current inverse matrix.
+                     

+                         This is useful to reduce the results'size. It is of course applied for
+                         each sample at a time.
+                     

+                         ROIs results are computed using a Median, not
+                         a Mean, of all points belonging to a given region.
+                     

+                         Cartool will check that ROIs are compatible
+                         with the other files, and will complain if needed...
+                 

+                     

+                         (4) Output Options
+                 

+                     

+                          
+                 

+                     

+                         Optional Base File Name Prefix:
+                 

+                     

+                         Specify here an optional prefix for all the output file names.
+                 

+                     

+                         Saving Files:
+                 

+                     

+                         A few options to tailor how you want to overflow your disk with files...
+                 

+                     

+                         Every Subjects' RIS
+                 

+                     

+                         Each input file will have a one-to-one corresponding output 
+                             
+                                 .ris
+                             
+                         
+                         file.
+                 

+                     

+                         + Every Epochs' RIS
+                 

+                     

+                         All Epochs will have a corresponding  
+                             
+                                 .ris
+                             
+                         
+                         file, which means, that could be huge.
+                 

+                     

+                         Computing Grand Averages
+                 

+                     

+                         This option, usually associated with ERP experiments, will gracefully
+                         compute the 
+                             average .ris
+                             of each condition
+                         .
+                     

+                         It will work correctly only if all the files have exactly the same
+                         lengths, across all conditions and all subjects.
+                 

+                     

+                         Computing Clusters Centroids
+                 

+                     

+                         This option is tailored for clusters of data (from the Fitting f.ex.). It
+                         will compute the mean template across each cluster of data. This
+                         might be even the only results of interest in that specific case...
+                 

+                     

+                         Z-Score Factors
+                 

+                     

+                         Save the Z-Score factors to file. This could be handy in case of
+                         re-computation by just reloading them - these factors take a bit of time
+                         to compute...
+                 

+                     

+                         Process
+                 

+                     

+                         Runs the computation.
+                     

+                     

+                         This button remains 
+                             disabled until all the parameter
+                             dialogs have received enough (and consistent) informations
+                         .
+                 

+                     

+                         Cancel
+                 

+                     

+                         Quit the dialog.
+                 

+                     

+                         Help
+                 

+                     

+                         Launch the Help to the right page (should be here...).
+                 

+         

+             Computing RIS - Technical points & hints
+         

+         

+             Checking the files consistency
+         

+         

+             Cartool will run your input files through an extensive set of consistency
+             rules. The purpose being first to avoid crashes, and second to check that you
+             haven't picked the wrong files.
+         

+         

+             The main consistency checks are the following:
+         

+         
    
+             
  • 
+                 Within the same EEG group:
      
+                     
    • Same number of electrodes
      • 
+                     
    • Same sampling frequency
      • 
+                     
    • Same duration, in case or ERPs
      • 
+                 
    
+             
    • 
+             
  • 
+                 Within different subject's groups:
      
+                     
    • Same number of files
      • 
+                     
    • Same duration in case of ERPs
      • 
+                 
    
+             
    • 
+             
  • 
+                 Across EEG, Inverse Matrix and Electrodes Coordinates:
      
+                     
    • Same number of electrodes between the matrix and the EEG
      • 
+                     
    • 
+                         Same number of electrodes between the Electrodes Coordinates and
+                         the EEG
+                     
      • 
+                 
    
+             
    • 
+             
  • 
+                 Across Inverse Matrix, Solution Points and ROIs:
      
+                     
    • 
+                         Without ROIs, same number of Solution Points with the Inverse
+                         Matrix
+                     
      • 
+                     
    • 
+                         With ROIs, same number of Solution Points with the ROIs number of
+                         regions
+                     
      • 
+                 
    
+             
    • 
+         

+         

+              
+         

+         

+             See here a simplified view of how files are checked, without ROIs:
+         

+         

+             files compatibility checks - no ROIs
+         

+         

+              
+         

+         

+             And here the same view, but with ROIs:
+         

+         

+             files compatibility checks - with ROIs
+         

+         

+             Spatial Filter
+         

+         

+             Applying the Spatial filter is strongly recommended before computing the
+             results of inverse solutions if there remains any transient artifacts, and/or
+             data is even slightly noisy. Both degrade the quality of the localization, or can even make
+             it totally erroneous.
+         

+         

+             The 
+                 
+                     exact specification of the
+                     Spatial Filter is here
+                 
+             .
+         

+         

+             The Spatial filter is a non-linear filter that will get rid of local
+             outliers, while also smoothing the overall map. It will, however, retain the
+             global aspect of the map's topography. See here an example of before (A) and
+             after (B) the Spatial filter, on the tracks (left) then on the maps (middle
+             and right): 
+         

+         

+             spatial filter
+         

+         

+             Background normalization via custom Z-Score
+         

+         

+             Due to various reasons, like an incorrect head geometry, or approximate skull
+             conductivity, some solution points will show more power than others.
+             Moreover, these power variations depend on each subject. Therefor, a 
+                 normalization step can only be applied after the results of inverse have been
+                 computed
+             , not before.
+         

+         

+             Before stepping into the formula, it is important to get the underlying idea
+             right. This normalization step will be 
+                 based solely on the background
+                 / noise activity
+             . The higher values are not used at all, so
+             to not bias the correction.
+         

+         

+             A custom Z-Score has been tailored to deal with the norm of dipoles. The idea is to convert from
+             a Chi-square distribution to a Normal
+             distribution (Equ. 1 and 2), then to a Z-Score (Equ. 3). Finally
+             data are offsetted by 3 standard deviations so as to remain positive (Equ. 6). The
+             tricky implementation part is all about estimating the Modes and (left part
+             of) Median of Absolute Deviation:
+         

+         

+             Z-Score equations for RIS
+         

+         

+             The resulting new solution points values remain positive, as to remain consistent with the original data,
+             but now with the noise having a Normal distribution centered on 1 (and a SD of 1/3).
+         

+         

+             See here an example of before (left picture) and after (right picture)
+             standardization, showing the color plot of the histogram (horizontal acis) of
+             each solution point (vertical axis):
+         

+         

+                    
+             
+         

+         

+             Templatize results
+         

+         

+             If one is interested on only having a 
+                 template of all active brains
+                 regions
+             , and does not care about power in the results, then the
+             Templatize options come in handy. This is typically used for Micro-tates
+             analysis f.ex.
+         

+         

+             Ranking will rank, and normalize to 1, every solution
+             points' results, for each sample / time point independently.
+         

+         

+             An additional Thresholding is available to 
+                 clear-out
+                 the lowest 90% of the data, hence keeping the top 10%
+             . Indeed, one
+             never looks at the lowest responses at all, it is mostly noise and/or some
+             possible inverse artefacts. It could be wise to not account for these!
+         

+         

+              
+         

+         

+             Here is an example of the effect of templatizing the results. Top data are
+             regulard ERP results, which power vary time. Corresponding inverse on the
+             right is kind of blurry. Bottom data is ranked + thresholded results, max
+             values are 1. Corresponding inverse are less blurry, but power information is
+             gone.
+         

+         

+             
+         

+         

+             Frequency files
+         

+         

+             Noteworthy is the fact that you can input frequency files,
+             and hence compute the results of inverse solution at different frequencies.
+         

+         

+             Here are the necessary steps to achieve that:
+         

+         
    
+             
  • 
+                 When computing the frequency results, use the  
+                     
+                         Wavelet for Source Space
+                     
+                   preset. It sets the 
+                     output format to be of Complex type
+                 , which is mandatory for our
+                 case here!
+             
    • 
+             
  • 
+                 Inverses will be computed at each frequency, 
+                     separately on the
+                 Real and 
+                     
+                         Imaginary
+                     
+                  parts,
+             
    • 
+             
  • 
+                 Then the square of the norm of the Real
+                     and
+                 Imaginary
+                     dipoles are
+                     summed
+                 ,
+             
    • 
+             
  • 
+                 Finally, it is strongly recommended to apply ROIs at
+                 that stage, to help reduce the size of the final data!
+             
    • 
+         

+         

+              
+         

+         

+             See here, for example, the results at 4 different frequencies, and for all
+             solution points (no ROIs):
+         

+         

+             

+             
+         

+         

+             Computing RIS - Results
+         

+         
    
+             
  • 
+                 For each input file, its corresponding <input file>.ris
+                 . These files can be directly used 
+                     for
+                     display
+                 .
+             
    • 
+             
  • 
+                 In case of Z-Score option, the Z-Score Mean and SD values in a file 
+                 <output file.ZScoreFactors>.sef 
+                 . The Z-Score file has 2 rows: one for the Mean and one for the Standard
+                 Deviation, for each solution point.
+             
    • 
+             
  • 
+                 Optionally for each group, the Mean of the
+                 group  <group #.Mean>.ris
+             
    • 
+         

+         

+              
+         

+         

+             Here is an example of ERP, top is the EEG on 204 electrodes, bottom the
+             transformed ris file. We can note that the EEG data are of course signed
+             data, more or less in the range -4..4, while the ris data are indeed centered
+             around 1:
+         

+         

+             before ris
+         

+         

+             after ris
+         

+         

+              
+         

+         

+             And here is an example of a map and its corresponding inverse display:
+         

+         

+             EEG vs RIS display
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         
 

+         
 

+     

  
 
\ No newline at end of file
diff --git a/docs/ReferenceGuide/computing-statistics.html b/docs/ReferenceGuide/computing-statistics.html
index b23e28ab..22458cee 100644
--- a/docs/ReferenceGuide/computing-statistics.html
+++ b/docs/ReferenceGuide/computing-statistics.html
@@ -8,1451 +8,1906 @@
 }
 
  
- 
-  

-   Statistics

-  

-    

-  

-   This page is about the Statistic tools implemented in Cartool, which 
-   can be used for example to test Tracks, GFPs, Topographies,
-    Segmentation and Inverse Solution results.

-  

-    

-  

-   Introduction

-  
-  

-   How to run the statistics

-  
-  

-   Results

-  

-   Introduction

-  

-   Which stats?

-  

-   Currently, only two sample statistics 
-   are implemented. That means it works only on 2 sets (or 
-   groups, or conditions) of data per subjects at a time, f.ex. one 
-   condition versus a control. If there are more than one condition, 
-   either wait for the Anova to be implemented, or run the tests pairs 
-   by pairs (though being less informative than an Anova).

-  

-    

-  

-   All the tests are available in two variations, which are paired 
-   and unpaired. You, and only you, know which one applies. 
-   Paired tests apply f.ex. (but not only) when the same subjects have 
-   performed both conditions. Then it is legitimate to stats on the 
-   differences between conditions, which paired tests are precisely doing.

-  

-    

-  

-   The formulas between paired and unpaired are different, the 
-   unpaired ones often resulting in less powerful tests. So prefer the 
-   paired tests if you can, but you can still see what happens in the 
-   unpaired case, though. Of course, paired conditions need to have the 
-   same number of files (i.e. of subjects) in each conditions.

-  

-   Which cases?

-  

-   The statistics can currently be applied in 3 different cases:

-  
    
-   
  • 
-   
    
-    On a set of files, one set per condition, each file being 
-    f.ex. an ERP or a RIS 
-    (for a given condition and a given subject). Each time
-     frame of the ERP will be tested sequentially,
-     or averaged.
    
-    
  • One file holds all the samples of one 
-    condition. The samples are written consecutively either in an ERP 
-    or a RIS file, 
-    overriding and cancelling the time dimension.
    
-    
  • On the results of the Fitting
-     process, provided as a multidimensional array in a .csv 
-    file. In this case, there is no time dimension, just a set variables 
-    to be tested. All groups / conditions are contained in a single file.
    
-   

-  

-   Two sample statistics

-  

-   Student t-test

-  

-   The t-test compares how the means of each conditions are far from 
-   each other, by using the standard deviation of the joined data to 
-   estimate the probability of being the same. The advantage of this 
-   method, en plus to be a standard one, is that it is very fast and 
-   straightforward to compute, and will always give the same results if 
-   run again.

-  

-   This is a parametric method, and the model behind it assumes that the 
-   data have a Gaussian ("normal") distribution. Practically, 
-   it also behaves quite well even if the data are not 
-   "normal", which is our case most of the time, unfortunately.

-  

-   Randomization

-  

-   Randomization is a general method that works on any variable you 
-   wish, and without any assumption regarding the actual data 
-   distribution, hence it is a non-parametric method.

-  

-   In our case, the test is done on the average across subjects of the 
-   variables tested (electrodes' tracks or inverse solution points' 
-   tracks). The main idea is that if the data were random, shuffling 
-   them somehow will not statistically make any difference as compared 
-   to the actual data configuration. The method runs by repeating 
-   "enough time" the shuffling so as to be able to estimate 
-   the probability that the data were only there by chance.

-  

-   As a consequence of the very nature of the method, results may 
-   slightly vary when run many times. Though, if the number of shuffling 
-   is big enough, it should be barely noticeable.

-  

-   TAnova

-  

-   Alias Topographic Anova, this is also part of the non-parametric / 
-   randomization techniques. Simply, the variable tested is the dissimilarity 
-   between conditions. It will tell if there is any topographical change 
-   between conditions, without accounting for intensity.

-  

-   How to run the statistics

-  

-   Called from the Tools
-    | Statistics menu, a dialog in two parts appears, 
-   both of them having to be correctly filled:

-  
-  

-   Files dialog

-  

-   

-    

-   

-  

-   
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-       
-     
-     
-       
-	   
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-   

-      

-       Groups of Files

-      

-        

-      

-       Data (samples) are Contained in:

-      

-       Specify here how data are organized within the files provided.

-      

-       Set of Files

-      

-       One file per condition and per subject, therefore the data to 
-       test have to be retrieved across a set of files for each time frame. 
-       This case has a time dimension 
-       that can be used.

-      

-       Files can be any ERP or RIS.

-      

-       1 File

-      

-       One file per condition, the data to be tested have been cut 
-       & paste-d into a single file. Data are then found 
-       sequentially into each file, cancelling any time dimension.

-      

-       Files can be any ERP or RIS.

-      

-       .csv File

-      

-       A multidimensional array in a .csv file,
-        the data are variables computed by the Fitting
-        process. In this case, there is no time dimension, but just a 
-       set variables to be tested.

-      

-       All groups / conditions are usually contained in the same file.

-      

-       Time interval

-      

-       If applicable, specify the time interval 
-       to be tested for the next input group(s).

-	  

-       Set this parameter before adding a new group!

-      

-       See this note to get the most of this parameter.

-      

-       from

-      

-       First time frame.

-      

-       to

-      

-       Last time frame.

-      

-       End of File

-      

-       Automatically set the last time frame to the actual end of the 
-       current file.

-      

-       Within this Time Interval, using:

-      

-       How to use this time interval for the next input group(s).

-	  

-       Set this parameter before adding a new group!

-	  

-       Basically, you specify if you want to take each time frame sequentially, 
-	   or use their mean instead.

-		

-      

-       Groups

-      

-       You can use the very convenient Drag & 
-       Drop feature here.

-      

-       Add New Group of Files

-      

-       Enter a new group (condition) of file(s). Depending on the data
-        organization, you have to specify either a set of files, 
-       a single file, or a .csv file for a 
-       single group.

-      

-       See this note about groups.

-      

-       Remove Last Group

-      

-       Does what it says (amazing).

-      

-       Use Last Group of Files

-      

-       Re-use the files (only) of the last group entered. Don't forget to 
-       change the time settings before 
-       clicking on this button.

-      

-       See this note about groups.

-      

-       Clear All Groups

-      

-       Clear out all the groups at once.

-      

-       Read Lists from File

-      

-       You can direclty retrieve the lists of groups previously saved.

-      

-       See also Drag & Drop.

-      

-       Write Lists to File

-      

-       You can save the lists of current groups into a file, in case you 
-       want to re-use them (much recommended!).

-      

-       See the file formats available.

-      

-       Sort Files within Lists

-      

-       A strange behavior of Windows is to not respect the order of the 
-       files dropped in a window. To help cure this silly habit, you can 
-       sort all the file names of all the groups already entered.

-      

-       Note however that Drag & Dropped files are automatically sorted.

-      

-       This is an important issue if you are going to do paired
-        tests. The exact match of files between the 2 conditions 
-       / groups is of the utmost importance. I can only strongly suggest to 
-       save your lists to file, and visually check the sequence.

-      

-       Number of Groups:

-      

-       Just a counter of the number of groups entered.

-      

-       Summary list of all groups

-      

-       One group is displayed per line, summarizing the time interval, the 
-       number of files / samples, and the file names of the first and last 
-       item of the group.

-      

-       Output Files

-      

-        

-      

-       Output Base File Name

-      

-       Specify here a basis for all the file names that will be 
-       generated during the averaging process.

-      

-       Output File Type:

-      

-       Pick the main output file type from a list.

-       Text files (.txt 
-	   .ep .eph) 
-	   might be easier to read into other packages, but take more space on the 
-	   disk.
Binary files (.sef .eeg .edf 
-	   .ris) are much more 
-	   compact, faster, and incorporate more informations into them. Either .sef 
-	   or BrainVision .eeg 
-	   are good choices.

-      

-       p Value Output:

-      

-       What actual values are being written in the output files:
    
-		  
  • p
    • 
-		  
  • (1 - p)
    • 
-		  
  • - log10 ( p )     
-		  (0.01 → 2; 0.001 → 3 etc...)
    • 
-	  

-		

-      

-       Options

-      

-        

-      

-       Open File(s) Upon Completion

-      

-       To automatically open (most of) the outputed files.

-      

-       Save Intermediate Results

-      

-       Save more result files with 
-       intermediate results. The files depend of course of each test performed.

-      

-       An option quite for connoisseur that may confuse you otherwise... Can 
-       be useful for figures or to double-check the results.

-       
-       

-      

-       << Previous  |  Next >>

-      

-       Use these buttons to navigate through the previous and next dialogs 
-       (if any).

-      

-       See which current dialog you are in, and to which other dialogs you 
-       connect, in the tab-like part at the top of the dialog under 
-       the title.

-        

-      

-       Process

-      

-       This button actually launches the statistics computation.

-      

-       This button remains disabled until all the parameter 
-       dialogs have received enough (and consistent) informations.

-      

-       Cancel

-      

-       Quit the dialog.

-      

-       Help

-      

-       Launch the Help to the right page (should be here...).

-  

-    

-  

-   Files dialog - Technical points & hints

-  

-   Time interval uses

-  

-   Before a new group is added, and if time
-    is relevant, you can specify how to make use of the specified time 
-   range:

-  
    
-	  
  • Default is to use each value sequentially
    • 
-	  
  • Otherwise you can compute a single baseline value 
-	  from that interval:
      
-		  
    • mean
      • 
-		  
    • median
      • 
-		  
    • min
      • 
-		  
    • max
      • 
-	  
    
-	  
    • 
-  

-  

-    

-  

-   Default for ERPs is to compare each time frame sequentially. It is also quite 
-   common to compare each value sequentially from post-stimulus interval, to a 
-   pre-stimulus baseline.

-  

-   There 4 available baseline formulas: the median being more robust than the 
-   mean; the min / max use depend on your data.

-  

-   How to test groups

-  
    
-   
  • 
-   
    
-    You can test a group of files against another group of files, in 
-    which case you simply input the groups one at a time.
    
-    
  • But you can also test a group (of files) against itself,
-     for example to test a baseline before an activity.
    
-    
  • This can be combined with any sequence
-     / average combinations, to test sequences or averages within 
-    the same or within different files.
    
-    
  • For two-sample tests, groups are taken 2 by 2 
-    from the list of groups, f.ex. groups 1 & 2, then 3 & 4, 
-    etc... If you want to re-use a group, you have to set the list accordingly.
    
-    
  • Internally, the computations are done as Group1 - 
-    (minus) Group2, Group3 - Group4, etc...
    
-    
  • The order of the groups is not important, testing 
-    GroupA vs GroupB is equivalent as testing GroupB vs GroupA. However 
-    the sign of the t value of the t-test will be inverted.
    
-   

-  

-   You can Drag & Drop these files 
-   directly from the Explorer:

-  

-   It is strongly recommended to use these Drag & Drop features 
-   which will tremendously ease your work:

-  
-  

-   File formats to save or retrieve the 
-   lists of groups

-  
    
-   
  • 
-   
    
-    .csv file
    
-    
  • .txt text file, with a similar format 
-    as the .csv format above, but separators used are tabs 
-    instead of commas (then rather a .tsv format).
    
-   

-  

-   Parameters dialog

-  

-   

-    

-   

-  

-   
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-       
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-       
-     
-     
-       
-    
-     
-     
-    
-       
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-       
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-   

-      

-       Variables to test

-      

-        

-      

-       Electrodes, GFP, or GEV, NumTF...:

-      

-       The list of variables to be tested, separated either by a 
-       space, a colon or a semi-colon.

-      

-       See this note for the full syntax and possibilities.

-      

-       Linking with XYZ:

-      

-       Optionally pointing to a file with the electrodes
-        coordinates and names. The names of the electrodes are taken 
-       from this file, overriding the original names from the EEG (i.e. 
-       you can rename the electrodes).

-       Be careful that the list above respect these names, otherwise you 
-       will get an error message.

-      

-       Constraints as in the link
-        mechanism must be respected, such as same number of electrodes, 
-       same order, etc...

-      

-       ROIs

-      

-       The ROIs to be used in the statistics.

-      

-       Note that ROIs and the Electrodes field above are mutually exclusive.

-      

-       Two-Sample Tests

-      

-       Right now, Cartool can test only two conditions at a time.

-      

-       Before running the tests, a parameters checking 
-       stage is applied according to the paired or unpaired tests.

-      

-       Unpaired- / Paired-

-      

-       Select which one option is relevant to your current analysis.

-	  

-       Before each test, some parameters checking 
-       is applied depending on the paired or unpaired selection.

-		   

-      

-       t-test

-      

-       Student's t-test.

-      

-       Formulas according to the paired / unpaired cases are:

-      
    
-       
  • 
-       
    
-        Paired: the mean of the differences between conditions.
    
-        
  • Unpaired: the difference of the means 
-         between conditions.
    
-       

-      

-       See also this note about the sign of the differences.

-      

-       Randomization

-      

-       See here for a short description.

-      

-       Formulas according to the paired / unpaired cases are:

-      
    
-       
  • 
-       
    
-        Paired: the mean of the differences between conditions.
    
-        
  • Unpaired: the difference of the means 
-         between conditions.
    
-       

-      

-       See the randomization technical points.

-      

-       See also this note about the sign of the differences.

-      

-       Topographic Anova

-      

-       See here for a short description.

-      

-       See the TAnova technical points.

-      

-       Parameters

-      

-        

-      

-       Presets:

-      

-       This is handy to quickly set the main parameters according to the 
-       most frequent uses, listed in the drop-down box.

-      

-       The most important parameters will be set, still some 
-       parameters have to be set manually! And, as usual, double 
-       check that all your settings make sense...

-      

-       Data Type:

-      

-        

-      

-       Only Positive

-      

-       Data consist of positive only, scalar data. This could be 
-       spikes from neuron recordings, or the Results of Inverse Solution, f.ex.

-      

-       This will logically turn off the Polarity & References options.

-      

-       See this point on 
-       positive data and also this point.

-      

-       Signed

-      

-       Signed scalar values, like, you know, EEG.

-      

-       Data reference

-      

-        

-      

-       No Reference

-      

-       Data are used as they come from files, no changes occur.

-      

-       Average Reference

-      

-       Data are average reference-d.

-      

-       Maps / Patterns Polarity:

-      

-        

-      

-       Ignore

-      

-       Polarity of maps does not matter, so ignore it. Inverted maps are 
-       considered the same (same underlying generators, but with reversed polarity).

-      

-       Used with the TAnova test on spontaneous EEG 
-       recordings or FFT Approximation.

-      

-       Account

-      

-       Polarity of maps matter, that is, inverted maps are indeed considered 
-       as different.

-      

-       Used for ERPs.

-      

-       Data level normalization

-      

-       This will rescale the data from each file by a given factor, and this 
-       is not to be misunderstood with normalization in the sense of 
-       a Gaussian distribution.

-      

-       None

-      

-       No rescaling.

-      

-       Mean Gfp

-      

-       Each file is divided by its mean Gfp across time, 
-       reducing inter-subjects variability.

-      

-       Mean Gfp paired

-      

-       The 2 files of the paired conditions (for a given subject) are
-        put together to compute the mean Gfp across time. The 
-       resulting factor is applied to both conditions equally.

-      

-       Doing so has the advantage of reducing the inter-subjects 
-       variability, still leaving untouched the differences between the conditions.
-        Using only the Mean Gfp in this case will certainly lead to 
-       erroneous results.

-      

-       Gfp at each TF

-      

-       For each time frame and for each file, the data are normalized by the Standard
-        Deviation of its electrodes / solution points.

-      

-       This is a means to cancel the overall intensity of the data, keeping 
-       only the topography (scalp electrodes case), or the brain areas 
-       configuration (inverse solution case).

-      

-       Accounting for Missing Values:

-      

-       This option is activated only when testing results 
-       from the Fitting process.

-      

-       Missing Value:

-      

-       Give the value that will signify that a value is to be ignored. Cartool's 
-	   default is -1.

-       Be careful that no real actual value can be set to that missing value.

-      

-       Number of randomizations

-      

-       The number of repetitions of the random process in the Randomization and 
-	   TAnova tests.

-      

-       See the randomization technical points.

-       Default is 5000 for a p-value of 0.01 (the lower the p-value, the higher 
-	   the number of repetitions has to be)

-      

-       Multiple-Tests Correction:

-      

-       You can pick from a list how to correct for type I errors when performing 
-	   multiple-tests.

-       Right now, you can choose between Bonferroni and FDR.

-       See this paragraph for more details.

-      

-       FDR value:

-      

-       For FDR correction, provide the actual discovery rate to be used. Default 
-	   is 5%.

-       Note that the FDR value is not a p-value.

-      

-       Thresholding p-value / q-values

-      

-       Threshold for the p-value (or q-value after the FDR Adjusted values).

-       Only the values below this percentage will be kept, otherwise p 
-	   will be set 
-       to 1.

-      

-       Min. Significant Duration:

-      

-       If the p-values (or q-values) are currently thresholded, it is 
-	   subsequently possible to test for a minimum successive significant 
-	   period.

-       Results only at least significant for the specified amount of time will 
-	   be kept.

-      

-       << Previous  |  Next >>

-      

-       Use these buttons to navigate through the previous and next dialogs 
-       (if any).

-      

-       See which current dialog you are in, and to which other dialogs you 
-       connect, in the tab-like part at the top of the dialog under 
-       the title.

-      	 

-      

-       Process

-      

-       This button actually launches the statistics computation.

-      

-       This button remains disabled until all the parameter 
-       dialogs have received enough (and consistent) informations.

-      

-       Cancel

-      

-       Quit the dialog.

-      

-       Help

-      

-       Launch the Help to the right page (should be here...).

-  

-    

-  

-   Parameters dialog - Technical points 
-   & hints

-  

-   Specifying the variables names

-  

-   The list of variables to be tested can be:

-  
    
-   
  • 
-   
    
-    A single variable.
    
-    
  • Many variables separated by a space, a colon, or a 
-    semi-colon, f.ex. "GEV MeanGfp MaxGfp".
    
-    
  • A range
-     of names, f.ex. e1-e100.
    
-    
  • A *, meaning 
-    all possible variables.
    
-   

-  

-   According to what you are testing, a 
-   variable name could be (not case sensitive):

-  
    
-   
  • 
-   
    
-    The name of an electrode, f.ex. e1 or Fpz.
    
-    
  • The name of a solution point, f.ex. sp1.
    
-    
  • The name of a computed track, as Gfp 
-    (Global Field Power) and Avg (Average). Dissimilarity has been 
-    disabled as it is meaningless to test it this way (see the TAnova 
-    rather, and here).
    
-    
  • A variable name computed by the Fitting
-     process:
-    
      
-     
    • The full name of the variable, f.ex. NumTF, MeanGfp,
-      TfBestCorr, etc...
      
-     
    • Only a part of a variable name, which will include 
-     all variables containing this part, f.ex.: TF for variables NumTF 
-     and TfBestCorr.
      
-     
    • The name of a given map, f.ex. map1 will 
-     test all the variables of map 1.
      
-     
    • Finally, only one variable for a single map, f.ex. map1_NumTF.
      
-    
    
-   

-  

-   ROIs & Statistics

-  

-   If a .rois file 
-   has been provided (also see Creating ROIs),
-    the following processings are done:

-  
    
-   
  • 
-   
    
-    data are read from files, with the requested reference,
    
-   
  • 
-   
    
-    variables belonging to the same roi are averaged together,
    
-   
  • 
-   
    
-    data level normalization can occur, with the GFPs of the original, 
-    non-averaged data (important!),
    
-   
  • 
-   
    
-    the test(s) then occur on the averages, properly accounting for 
-    the data reduction (f.ex. number of variables for Bonferroni),
    
-   
  • 
-   
    
-    the output names for the variables are set to the ROIs names.
    
-   

-  

-    

-  

-   This is the best way to tests your ROIs in Cartool!

-  

-   First, the normalization is sure to be correct, with the 
-   original GFPs. In the case you compute the ROIs yourself before 
-   the stats, make sure to do all level corrections at that stage (and 
-   check off normalization in the stats!). This is your responsability! 
-   BTW, re-referencing has the same problems, for the same reasons.

-  

-   Second, the ROIs averaging is done on-the-fly, meaning you 
-   don't have to create these averaged files yourself. That is, less 
-   errors, less time wasted, and all the flexibility to test for other 
-   ROIs. As a side effect, you can also recover the averaged ROIs data, 
-   if you asked for saving intermediate results.

-  

-   Cartool will finally correctly report the number of ROIs as 
-   being the number or variables tested. This is used for 
-   Bonferroni correction f.ex.

-  

-   Parameters checking

-  
    
-   
  • 
-   
    
-    Before running any test, a procedure is run on the parameters to 
-    check their consistencies. It checks the time boundaries for each 
-    file, then between the files, the number of files in each group, 
-    etc... Time limits issues are resolved here (End of File limits, etc...)
    
-   
  • 
-   
    
-    One checking is done before all unpaired tests (which are run 
-    first), because it is the less restrictive case.
    
-   
  • 
-   
    
-    Then a second checking is done when entering the paired tests.
-     In some rare cases, this might apparently lead to inconsistencies 
-    between the parameters actually used in the paired and unpaired 
-    tests. For example, if the number of files is not equal between the 
-    two conditions (which shouldn't be tested as paired, BTW), then the 
-    actual number of files taken into account would be the minimum of the 
-    two sets.
    
-   

-  

-   Number of repetitions for the 
-   Randomization process

-  
    
-   
  • 
-   
    
-    In the paired case, Cartool tries as much as possible to enumerate 
-    all the 2n cases.
    
-   
  • 
-   
    
-    In the unpaired case, the number of randomization is a 
-    compromise between the number of variables to test and the time spent 
-    into the process. Still, the number of repetitions remains quite 
-    high, starting from about 16000 repetitions down to a minimum 
-    of 5000 (this would be a very good reason to ask your boss for 
-    a more powerful PC).
    
-   
    
-    Cartool does not try to enumerate the unpaired cases, because 16C8 
-    is already 12870!
    
-   
  • 
-   
    
-    If you override the number of repetition, it will apply to both the 
-    paired and the unpaired tests, cancelling the paired enumeration.
    
-   
  • 
-   
    
-    Be careful though, overriding the number of repetitions with a too 
-    low value can (and indeed, will) affect the precision of the results, 
-    or even completely miss the results.
    
-   

-  
Multiple-Tests Correction

-  
When simultaneously testing multiple electrodes / solution points, it is a 
-  recommended practice to correct for type I errors.

-  
Cartool offers currently 4 options:

-  
    
-	  
  • No correction. Still usable if you don't have enough 
-	  data, and to outline a trend in your data.
    • 
-	  
  • Bonferroni correction. p-values are rescaled by the 
-	  number of simultaneously tested variables.
    This is however 
-	  well-acknowledge to be an over-kill correction, and most data don't 
-	  survive it ("Bonferronied to death")!
    • 
-	  
  • FDR (False Discovery Rate) correction. User specifies 
-	  the acceptable proportion of tests that can have a type I error, instead 
-	  of a single one as per the Bonferroni case. A usual accepatable value is 
-	  5%, but it can be higher than that.
    Cartool offers 2 FDR outputs:
    
-	  
      
-		  
    • FDR - Optimally Thresholding p-value:
      It finds the 
-		  optimal thresholding p-value for the current set of p-values.
      
-		  The ouput values are still p-values, which can be an interesting 
-		  property.
      • 
-		  
    • FDR - Adjusting p-values to q-values:
      All p-values are 
-		  converted to Adjusted values q-values.
      Then you 
-		  can proceed with the usual "p-values" thresholding, like 1% or 5%.
      
-		  But the output are no more p-values.
      • 
-	  
    
-	  
    • 
-  

-  
 

-  
The two FDR options should somehow lead to the same results, the main 
-  difference being the first one still outputs p-values, while not the second 
-  one.

-  
 

-  
Controlling the False Discovery Rate: A Practical and Powerful Approach to Multiple Testing,
+ 
+     

+         

+             Statistics
+         

+         

+              
+         

+         

+             This page is about the Statistic tools implemented in Cartool, which
+             can be used for example to test Tracks, GFPs, Topographies,
+             Segmentation and Inverse Solution results.
+         

+         

+              
+         

+         

+             Introduction
+         

+         
+         

+             How to run the statistics
+         

+         
+         

+             Results
+         

+         

+             Introduction
+         

+         

+             Which stats?
+         

+         

+             Currently, only two sample statistics
+             are implemented. That means it works only on 2 sets (or
+             groups, or conditions) of data per subjects at a time, f.ex. one
+             condition versus a control. If there are more than one condition,
+             either wait for the Anova to be implemented, or run the tests pairs
+             by pairs (though being less informative than an Anova).
+         

+         

+              
+         

+         

+             All the tests are available in two variations, which are paired
+             and unpaired. You, and only you, know which one applies.
+             Paired tests apply f.ex. (but not only) when the same subjects have
+             performed both conditions. Then it is legitimate to stats on the
+             differences between conditions, which paired tests are precisely doing.
+         

+         

+              
+         

+         

+             The formulas between paired and unpaired are different, the
+             unpaired ones often resulting in less powerful tests. So prefer the
+             paired tests if you can, but you can still see what happens in the
+             unpaired case, though. Of course, paired conditions need to have the
+             same number of files (i.e. of subjects) in each conditions.
+         

+         

+             Which cases?
+         

+         

+             The statistics can currently be applied in 3 different cases:
+         

+         
    
+             
  • 
+                 
    
+                     On a set of files, one set per condition, each file being
+                     f.ex. an ERP or a RIS
+                     (for a given condition and a given subject). Each 
+                         time
+                         frame
+                      of the ERP will be tested 
+                         sequentially,
+                         or averaged
+                     .
    
+             
  • 
+                 One file holds all the samples of one
+                 condition. The samples are written consecutively either in an ERP
+                 or a RIS file,
+                 overriding and cancelling the time dimension.
    
+             
  • 
+                 On the 
+                     results of the 
+                         Fitting
+                         process
+                     
+                 , provided as a multidimensional array in a .csv
+                 file. In this case, there is no time dimension, just a set variables
+                 to be tested. All groups / conditions are contained in a single file.
    
+         

+         

+             Two sample statistics
+         

+         

+             Student t-test
+         

+         

+             The t-test compares how the means of each conditions are far from
+             each other, by using the standard deviation of the joined data to
+             estimate the probability of being the same. The advantage of this
+             method, en plus to be a standard one, is that it is very fast and
+             straightforward to compute, and will always give the same results if
+             run again.
+         

+         

+             This is a parametric method, and the model behind it assumes that the
+             data have a Gaussian ("normal") distribution. Practically,
+             it also behaves quite well even if the data are not
+             "normal", which is our case most of the time, unfortunately.
+         

+         

+             Randomization
+         

+         

+             Randomization is a general method that works on any variable you
+             wish, and without any assumption regarding the actual data
+             distribution, hence it is a non-parametric method.
+         

+         

+             In our case, the test is done on the average across subjects of the
+             variables tested (electrodes' tracks or inverse solution points'
+             tracks). The main idea is that if the data were random, shuffling
+             them somehow will not statistically make any difference as compared
+             to the actual data configuration. The method runs by repeating
+             "enough time" the shuffling so as to be able to estimate
+             the probability that the data were only there by chance.
+         

+         

+             As a consequence of the very nature of the method, results may
+             slightly vary when run many times. Though, if the number of shuffling
+             is big enough, it should be barely noticeable.
+         

+         

+             TAnova
+         

+         

+             Alias Topographic Anova, this is also part of the non-parametric /
+             randomization techniques. Simply, the variable tested is the dissimilarity
+             between conditions. It will tell if there is any topographical change
+             between conditions, without accounting for intensity.
+         

+         

+             How to run the statistics
+         

+         

+             Called from the 
+                 
+                     Tools
+                     | Statistics
+                 
+              menu, a dialog in two parts appears,
+             both of them having to be correctly filled:
+         

+         
+         

+             Files dialog
+         

+         

+             

+                 
+             

+         

+         

+             
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+             

+                         

+                             Groups of Files
+                     

+                         

+                              
+                     

+                         

+                             Data (samples) are Contained in:
+                     

+                         

+                             Specify here how data are organized within the files provided.
+                     

+                         

+                             Set of Files
+                     

+                         

+                             One file per condition and per subject, therefore the data to
+                             test have to be retrieved across a set of files for each time frame.
+                             This case has a time dimension
+                                 that can be used
+                             .
+                         

+                         

+                             Files can be any ERP or RIS.
+                     

+                         

+                             1 File
+                     

+                         

+                             One file per condition, the data to be tested have been 
+                                 cut
+                                 & paste
+                             -d into a single file. Data are then found
+                             sequentially into each file, cancelling any time dimension.
+                         

+                         

+                             Files can be any ERP or RIS.
+                     

+                         

+                             .csv File
+                     

+                         

+                             A multidimensional array in a .csv file,
+                             the data are variables computed by the 
+                                 Fitting
+                                 process
+                             . In this case, there is no time dimension, but just a
+                             set variables to be tested.
+                         

+                         

+                             All groups / conditions are usually contained in the same file.
+                     

+                         

+                             Time interval
+                     

+                         

+                             If applicable, specify the time interval
+                             to be tested for the next input group(s).
+                         

+                         

+                             Set this parameter before adding a new group!
+                         

+                         

+                             See this note to get the most of this parameter.
+                     

+                         

+                             from
+                     

+                         

+                             First time frame.
+                     

+                         

+                             to
+                     

+                         

+                             Last time frame.
+                     

+                         

+                             End of File
+                     

+                         

+                             Automatically set the last time frame to the 
+                                 actual end of the
+                                 current file
+                             .
+                     

+                         

+                             Within this Time Interval, using:
+                     

+                         

+                             How to use this time interval for the next input group(s).
+                         

+                         

+                             Set this parameter before adding a new group!
+                         

+                         

+                             Basically, you specify if you want to take each time frame sequentially,
+                             or use their mean instead.
+                         

+                     

+                         

+                             Groups
+                     

+                         

+                             You can use the very convenient 
+                                 Drag &
+                                 Drop feature
+                              here.
+                     

+                         

+                             Add New Group of Files
+                     

+                         

+                             Enter a new group (condition) of file(s). Depending on the 
+                                 data
+                                 organization
+                             , you have to specify either a set of files,
+                             a single file, or a .csv file for a
+                             single group.
+                         

+                         

+                             See this note about groups.
+                     

+                         

+                             Remove Last Group
+                     

+                         

+                             Does what it says (amazing).
+                     

+                         

+                             Use Last Group of Files
+                     

+                         

+                             Re-use the files (only) of the last group entered. Don't forget to
+                             change the time settings before
+                             clicking on this button.
+                         

+                         

+                             See this note about groups.
+                     

+                         

+                             Clear All Groups
+                     

+                         

+                             Clear out all the groups at once.
+                     

+                         

+                             Read Lists from File
+                     

+                         

+                             You can direclty retrieve the lists of groups previously saved.
+                         

+                         

+                             See also Drag & Drop.
+                     

+                         

+                             Write Lists to File
+                     

+                         

+                             You can save the lists of current groups into a file, in case you
+                             want to re-use them (much recommended!).
+                         

+                         

+                             See the file formats available.
+                     

+                         

+                             Sort Files within Lists
+                     

+                         

+                             A strange behavior of Windows is to not respect the order of the
+                             files dropped in a window. To help cure this silly habit, you can
+                             sort all the file names of all the groups already entered.
+                         

+                         

+                             Note however that Drag & Dropped files are automatically sorted.
+                         

+                         

+                             This is an important issue if you are going to do 
+                                 paired
+                                 tests
+                             . The exact match of files between the 2 conditions
+                             / groups is of the utmost importance. I can only strongly suggest to
+                             save your lists to file, and visually check the sequence.
+                     

+                         

+                             Number of Groups:
+                     

+                         

+                             Just a counter of the number of groups entered.
+                     

+                         

+                             Summary list of all groups
+                     

+                         

+                             One group is displayed per line, summarizing the time interval, the
+                             number of files / samples, and the file names of the first and last
+                             item of the group.
+                     

+                         

+                             Output Files
+                     

+                         

+                              
+                     

+                         

+                             Output Base File Name
+                     

+                         

+                             Specify here a basis for all the file names that will be
+                             generated during the averaging process.
+                     

+                         

+                             Output File Type:
+                     

+                         

+                             Pick the main output file type from a list.
+                         

+                             Text files (.txt 
+                                 
+                                     .ep
+                                 
+                              .eph)
+                             might be easier to read into other packages, but take more space on the
+                             disk.
Binary files (.sef .eeg .edf 
+                                 
+                                     .ris
+                                 
+                             ) are much more
+                             compact, faster, and incorporate more informations into them. Either .sef
+                             or BrainVision .eeg
+                             are good choices.
+                     

+                         

+                             p Value Output:
+                     

+                         

+                             What actual values are being written in the output files:
    
+                                 
  • p
    • 
+                                 
  • (1 - p)
    • 
+                                 
  • 
+                                     - log10 ( p )    
+                                     (0.01 → 2; 0.001 → 3 etc...)
+                                 
    • 
+                             

+                     

+                         

+                             Options
+                     

+                         

+                              
+                     

+                         

+                             Open File(s) Upon Completion
+                     

+                         

+                             To automatically open (most of) the outputed files.
+                     

+                         

+                             Save Intermediate Results
+                     

+                         

+                             Save more result files with
+                             intermediate results. The files depend of course of each test performed.
+                         

+                         

+                             An option quite for connoisseur that may confuse you otherwise... Can
+                             be useful for figures or to double-check the results.
+                     

+                          
+                     
+                          
+                     

+                         

+                             << Previous  |  Next >>
+                     

+                         

+                             Use these buttons to navigate through the previous and next dialogs
+                             (if any).
+                         

+                         

+                             See which current dialog you are in, and to which other dialogs you
+                             connect, in the tab-like part at the top of the dialog under
+                             the title.
+                         

+                     

+                         

+                             Process
+                     

+                         

+                             This button actually launches the statistics computation.
+                         

+                         

+                             This button remains 
+                                 disabled until all the parameter
+                                 dialogs have received enough (and consistent) informations
+                             .
+                     

+                         

+                             Cancel
+                     

+                         

+                             Quit the dialog.
+                     

+                         

+                             Help
+                     

+                         

+                             Launch the Help to the right page (should be here...).
+                     

+         

+         

+              
+         

+         

+             Files dialog - Technical points & hints
+         

+         

+             Time interval uses
+         

+         

+             Before a new group is added, and if 
+                 time
+                 is relevant
+             , you can specify how to make use of the specified time
+             range:
+         

+         
    
+             
  • Default is to use each value sequentially
    • 
+             
  • 
+                 Otherwise you can compute a single baseline value
+                 from that interval:
      
+                     
    • mean
      • 
+                     
    • median
      • 
+                     
    • min
      • 
+                     
    • max
      • 
+                 
    
+             
    • 
+         

+         

+              
+         

+         

+             Default for ERPs is to compare each time frame sequentially. It is also quite
+             common to compare each value sequentially from post-stimulus interval, to a
+             pre-stimulus baseline.
+         

+         

+             There 4 available baseline formulas: the median being more robust than the
+             mean; the min / max use depend on your data.
+         

+         

+             How to test groups
+         

+         
    
+             
  • 
+                 
    
+                     You can test a group of files against another group of files, in
+                     which case you simply input the groups one at a time.
    
+             
  • 
+                 But you can also test a group (of files) against itself,
+                 for example to test a baseline before an activity.
    
+             
  • 
+                 This can be combined with any 
+                     sequence
+                     / average combinations
+                 , 
+                     to test sequences or averages within
+                     the same or within different files
+                 .
    
+             
  • 
+                 For two-sample tests, groups are taken 2 by 2
+                 from the list of groups, f.ex. groups 1 & 2, then 3 & 4,
+                 etc... If you want to re-use a group, you have to set the list accordingly.
    
+             
  • 
+                 Internally, the computations are done as Group1 -
+                 (minus) Group2, Group3 - Group4, etc...
    
+             
  • 
+                 The order of the groups is not important, testing
+                 GroupA vs GroupB is equivalent as testing GroupB vs GroupA. However
+                 the sign of the t value of the t-test will be inverted.
    
+         

+         

+             You can Drag & Drop these files
+             directly from the Explorer:
+         

+         

+             It is strongly recommended to use these Drag & Drop features
+             which will tremendously ease your work:
+         

+         
+         

+             File formats to save or retrieve the
+             lists of groups
+         

+         
    
+             
  • 
+                 
    
+                     .csv file
    
+             
  • 
+                 .txt text file, with a similar format
+                 as the .csv format above, but separators used are tabs
+                 instead of commas (then rather a .tsv format).
    
+         

+         

+             Parameters dialog
+         

+         

+             

+                 
+             

+         

+         

+             
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             

+                         

+                             Variables to test
+                     

+                         

+                              
+                     

+                         

+                             Electrodes, GFP, or GEV, NumTF...:
+                     

+                         

+                             The list of variables to be tested, separated either by a
+                             space, a colon or a semi-colon.
+                         

+                         

+                             See this note for the full syntax and possibilities.
+                     

+                         

+                             Linking with XYZ:
+                     

+                         

+                             Optionally pointing to a file with the 
+                                 electrodes
+                                 coordinates
+                              and names. The 
+                                 names of the electrodes are taken
+                                 from this file
+                             , overriding the original names from the EEG (i.e.
+                             you can rename the electrodes).

+                             Be careful that the list above respect these names, otherwise you
+                             will get an error message.
+                         

+                         

+                             Constraints as in the 
+                                 link
+                                 mechanism
+                              must be respected, such as same number of electrodes,
+                             same order, etc...
+                     

+                         

+                             ROIs
+                     

+                         

+                             The ROIs to be used in the statistics.
+                         

+                         

+                             Note that ROIs and the Electrodes field above are mutually exclusive.
+                     

+                         

+                             Two-Sample Tests
+                     

+                         

+                             Right now, Cartool can test only two conditions at a time.
+                         

+                         

+                             Before running the tests, a parameters checking
+                             stage is applied according to the paired or unpaired tests.
+                     

+                         

+                             Unpaired- / Paired-
+                     

+                         

+                             Select which one option is relevant to your current analysis.
+                         

+                         

+                             Before each test, some parameters checking
+                             is applied depending on the paired or unpaired selection.
+                         

+                     

+                         

+                             t-test
+                     

+                         

+                             Student's t-test.
+                         

+                         

+                             Formulas according to the paired / unpaired cases are:
+                         

+                         
    
+                             
  • 
+                                 
    
+                                     Paired: the mean of the differences between conditions.
    
+                             
  • 
+                                 Unpaired: the difference of the means 
+                                 between conditions.
+         
    
+         

+         

+             See also this note about the sign of the differences.

+                     

+                         Randomization
+                 

+                     

+                         See here for a short description.
+                     

+                     

+                         Formulas according to the paired / unpaired cases are:
+                     

+                     
    
+                         
  • 
+                             
    
+                                 Paired: the mean of the differences between conditions.
    
+                         
  • 
+                             Unpaired: the difference of the means 
+                             between conditions.
+         
    
+         

+         

+             See the randomization technical points.
+         

+         

+             See also this note about the sign of the differences.

+                     

+                         Topographic Anova
+                 

+                     

+                         See here for a short description.
+                     

+                     

+                         See the TAnova technical points.
+                 

+                     

+                         Parameters
+                 

+                     

+                          
+                 

+                     

+                         Presets:
+                 

+                     

+                         This is handy to quickly set the main parameters according to the
+                         most frequent uses, listed in the drop-down box.
+                     

+                     

+                         The most important parameters will be set, still 
+                             
+                                 some
+                                 parameters have to be set manually!
+                             
+                          And, as usual, double
+                         check that all your settings make sense...
+                 

+                     

+                         Data Type:
+                 

+                     

+                          
+                 

+                     

+                         Only Positive
+                 

+                     

+                         Data consist of positive only, scalar data. This could be
+                         spikes from neuron recordings, or the Results of Inverse Solution, f.ex.
+                     

+                     

+                         This will logically turn off the Polarity & References options.
+                     

+                     

+                         See this 
+                             point on
+                             positive data
+                          and also this point.
+                 

+                     

+                         Signed
+                 

+                     

+                         Signed scalar values, like, you know, EEG.
+                 

+                     

+                         Data reference
+                 

+                     

+                          
+                 

+                     

+                         No Reference
+                 

+                     

+                         Data are used as they come from files, no changes occur.
+                 

+                     

+                         Average Reference
+                 

+                     

+                         Data are average reference-d.
+                 

+                     

+                         Maps / Patterns Polarity:
+                 

+                     

+                          
+                 

+                     

+                         Ignore
+                 

+                     

+                         Polarity of maps does not matter, so ignore it. Inverted maps are
+                         considered the same (same underlying generators, but with reversed polarity).
+                     

+                     

+                         Used with the TAnova test on spontaneous EEG
+                         recordings or FFT Approximation.
+                 

+                     

+                         Account
+                 

+                     

+                         Polarity of maps matter, that is, inverted maps are indeed considered
+                         as different.
+                     

+                     

+                         Used for ERPs.
+                 

+                     

+                         Data level normalization
+                 

+                     

+                         This will rescale the data from each file by a given factor, and this
+                         is not to be misunderstood with normalization in the sense of
+                         a Gaussian distribution.
+                 

+                     

+                         None
+                 

+                     

+                         No rescaling.
+                 

+                     

+                         Mean Gfp
+                 

+                     

+                         Each file is divided by its mean Gfp across time,
+                         reducing inter-subjects variability.
+                 

+                     

+                         Mean Gfp paired
+                 

+                     

+                         The 2 files of the paired conditions (for a given subject) 
+                             are
+                             put together
+                          to compute the mean Gfp across time. The
+                         resulting factor is applied to both conditions equally.
+                     

+                     

+                         Doing so has the advantage of reducing the inter-subjects
+                         variability, still leaving untouched the differences between the conditions.
+                         Using only the Mean Gfp in this case will certainly lead to
+                         erroneous results.
+                 

+                     

+                         Gfp at each TF
+                 

+                     

+                         For each time frame and for each file, the data are normalized by the 
+                             Standard
+                             Deviation
+                          of its electrodes / solution points.
+                     

+                     

+                         This is a means to cancel the overall intensity of the data, keeping
+                         only the topography (scalp electrodes case), or the brain areas
+                         configuration (inverse solution case).
+                 

+                     

+                         Accounting for Missing Values:
+                 

+                     

+                         This option is activated only when testing results
+                         from the Fitting process.
+                 

+                     

+                         Missing Value:
+                 

+                     

+                         Give the value that will signify that a value is to be ignored. Cartool's
+                         default is -1.
+                     

+                         Be careful that no real actual value can be set to that missing value.
+                 

+                     

+                         Number of randomizations
+                 

+                     

+                         The number of repetitions of the random process in the Randomization and
+                         TAnova tests.
+                     

+                     

+                         See the randomization technical points.
+                     

+                         Default is 5000 for a p-value of 0.01 (the lower the p-value, the higher
+                         the number of repetitions has to be)
+                 

+                     

+                         Multiple-Tests Correction:
+                 

+                     

+                         You can pick from a list how to correct for type I errors when performing
+                         multiple-tests.
+                     

+                         Right now, you can choose between Bonferroni and FDR.
+                     

+                         See this paragraph for more details.
+                 

+                     

+                         FDR value:
+                 

+                     

+                         For FDR correction, provide the actual discovery rate to be used. Default
+                         is 5%.
+                     

+                         Note that the FDR value is not a p-value.
+                 

+                     

+                         Thresholding p-value / q-values
+                 

+                     

+                         Threshold for the p-value (or q-value after the FDR Adjusted values).
+                     

+                         
+                             Only the values below this percentage will be kept, otherwise p
+                             will be set
+                             to 1.
+                         
+                 

+                     

+                         Min. Significant Duration:
+                 

+                     

+                         If the p-values (or q-values) are currently thresholded, it is
+                         subsequently possible to test for a minimum successive significant
+                         period.
+                     

+                         Results only at least significant for the specified amount of time will
+                         be kept.
+                 

+                     

+                         << Previous  |  Next >>
+                 

+                     

+                         Use these buttons to navigate through the previous and next dialogs
+                         (if any).
+                     

+                     

+                         See which current dialog you are in, and to which other dialogs you
+                         connect, in the tab-like part at the top of the dialog under
+                         the title.
+                     

+                 

+                     

+                         Process
+                 

+                     

+                         This button actually launches the statistics computation.
+                     

+                     

+                         This button remains 
+                             disabled until all the parameter
+                             dialogs have received enough (and consistent) informations
+                         .
+                 

+                     

+                         Cancel
+                 

+                     

+                         Quit the dialog.
+                 

+                     

+                         Help
+                 

+                     

+                         Launch the Help to the right page (should be here...).
+                 

+         

+         

+              
+         

+         

+             Parameters dialog - Technical points
+             & hints
+         

+         

+             Specifying the variables names
+         

+         

+             The list of variables to be tested can be:
+         

+         
    
+             
  • 
+                 
    
+                     A single variable.
    
+             
  • 
+                 Many variables separated by a space, a colon, or a
+                 semi-colon, f.ex. "GEV MeanGfp MaxGfp".
    
+             
  • 
+                 A 
+                     range
+                     of names
+                 , f.ex. e1-e100.
    
+             
  • 
+                 A *, meaning
+                 all possible variables.
    
+         

+         

+             According to what you are testing, a
+             variable name could be (not case sensitive):
+         

+         
    
+             
  • 
+                 
    
+                     The name of an electrode, f.ex. e1 or Fpz.
    
+             
  • The name of a solution point, f.ex. sp1.
    
+             
  • 
+                 The name of a computed track, as Gfp
+                 (Global Field Power) and Avg (Average). Dissimilarity has been
+                 disabled as it is meaningless to test it this way (see the TAnova
+                 rather, and here).
    
+             
  • 
+                 A variable name computed by the 
+                     Fitting
+                     process
+                 :
+                 
      
+                     
    • 
+                         The full name of the variable, f.ex. NumTF, MeanGfp,
+                         TfBestCorr, etc...
      
+                     
    • 
+                         Only a part of a variable name, which will include
+                         all variables containing this part, f.ex.: TF for variables NumTF
+                         and TfBestCorr.
      
+                     
    • 
+                         The name of a given map, f.ex. map1 will
+                         test all the variables of map 1.
      
+                     
    • Finally, only one variable for a single map, f.ex. map1_NumTF.
      
+                 
    
+         

+         

+             ROIs & Statistics
+         

+         

+             If a .rois file
+             has been provided (also see Creating ROIs),
+             the following processings are done:
+         

+         
    
+             
  • 
+                 
    
+                     data are read from files, with the requested reference,
+                 
    
+             
  • 
+                 
    
+                     variables belonging to the same roi are averaged together,
+                 
    
+             
  • 
+                 
    
+                     data level normalization can occur, with the GFPs of the original,
+                     non-averaged data (important!),
+                 
    
+             
  • 
+                 
    
+                     the test(s) then occur on the averages, 
+                         properly accounting for
+                         the data reduction
+                      (f.ex. number of variables for Bonferroni),
+                 
    
+             
  • 
+                 
    
+                     the output names for the variables are set to the ROIs names.
+                 
    
+         

+         

+              
+         

+         

+             This is the best way to tests your ROIs in Cartool!
+         

+         

+             First, the normalization is sure to be correct, with the
+             original GFPs. In the case you compute the ROIs yourself before
+             the stats, make sure to do all level corrections at that stage (and
+             check off normalization in the stats!). This is your responsability!
+             BTW, re-referencing has the same problems, for the same reasons.
+         

+         

+             Second, the ROIs averaging is done on-the-fly, meaning you
+             don't have to create these averaged files yourself. That is, less
+             errors, less time wasted, and all the flexibility to test for other
+             ROIs. As a side effect, you can also recover the averaged ROIs data,
+             if you asked for saving intermediate results.
+         

+         

+             Cartool will finally correctly report the number of ROIs as
+             being the number or variables tested. This is used for
+             Bonferroni correction f.ex.
+         

+         

+             Parameters checking
+         

+         
    
+             
  • 
+                 
    
+                     Before running any test, a procedure is run on the parameters to
+                     check their consistencies. It checks the time boundaries for each
+                     file, then between the files, the number of files in each group,
+                     etc... Time limits issues are resolved here (End of File limits, etc...)
+                 
    
+             
  • 
+                 
    
+                     One checking is done before all unpaired tests (which are run
+                     first), because it is the less restrictive case.
+                 
    
+             
  • 
+                 
    
+                     Then a second checking is done when entering the paired tests.
+                     In some rare cases, this might apparently lead to inconsistencies
+                     between the parameters actually used in the paired and unpaired
+                     tests. For example, if the number of files is not equal between the
+                     two conditions (which shouldn't be tested as paired, BTW), then the
+                     actual number of files taken into account would be the minimum of the
+                     two sets.
+                 
    
+         

+         

+             Number of repetitions for the
+             Randomization process
+         

+         
    
+             
  • 
+                 
    
+                     In the paired case, Cartool tries as much as possible to enumerate
+                     all the 2n cases.
+                 
    
+             
  • 
+                 
    
+                     In the unpaired case, the number of randomization is a
+                     compromise between the number of variables to test and the time spent
+                     into the process. Still, the number of repetitions remains quite
+                     high, starting from about 16000 repetitions down to a minimum
+                     of 5000 (this would be a very good reason to ask your boss for
+                     a more powerful PC).
+                 
    
+                 
    
+                     Cartool does not try to enumerate the unpaired cases, because 16C8
+                     is already 12870!
+                 
    
+             
  • 
+                 
    
+                     If you override the number of repetition, it will apply to both the
+                     paired and the unpaired tests, cancelling the paired enumeration.
+                 
    
+             
  • 
+                 
    
+                     Be careful though, overriding the number of repetitions with a too
+                     low value can (and indeed, will) affect the precision of the results,
+                     or even completely miss the results.
+                 
    
+         

+         
Multiple-Tests Correction

+         

+             When simultaneously testing multiple electrodes / solution points, it is a
+             recommended practice to correct for type I errors.
+         

+         
Cartool offers currently 4 options:

+         
    
+             
  • 
+                 No correction. Still usable if you don't have enough
+                 data, and to outline a trend in your data.
+             
    • 
+             
  • 
+                 Bonferroni correction. p-values are rescaled by the
+                 number of simultaneously tested variables.
    This is however
+                 well-acknowledge to be an over-kill correction, and most data don't
+                 survive it ("Bonferronied to death")!
+             
    • 
+             
  • 
+                 FDR (False Discovery Rate) correction. User specifies
+                 the acceptable proportion of tests that can have a type I error, instead
+                 of a single one as per the Bonferroni case. A usual accepatable value is
+                 5%, but it can be higher than that.
    Cartool offers 2 FDR outputs:
    
+                 
      
+                     
    • 
+                         FDR - Optimally Thresholding p-value:
      It finds the 
+                             optimal thresholding p-value
+                          for the current set of p-values.
      
+                         The ouput values are still p-values, which can be an interesting
+                         property.
+                     
      • 
+                     
    • 
+                         FDR - Adjusting p-values to q-values:
      All p-values are
+                         converted to Adjusted values q-values.
      Then you
+                         can proceed with the usual "p-values" thresholding, like 1% or 5%.
      
+                         But the output are no more p-values.
+                     
      • 
+                 
    
+             
    • 
+         

+         
 

+         

+             The two FDR options should somehow lead to the same results, the main
+             difference being the first one still outputs p-values, while not the second
+             one.
+         

+         
 

+         
Controlling the False Discovery Rate: A Practical and Powerful Approach to Multiple Testing,
 Yoav Benjamini, Yosef Hochberg,
 Journal of the Royal Statistical Society. Series B (Methodological), Vol. 57, No. 1 (1995), pp. 289-300. 

-  

-   TAnova (Topographic Anova) method

-  

-   The following randomization procedure is applied (for each time frame):

-  
    
-   
  • 
-   
    
-    All the maps are average referenced, then normalized,
    
-    
  • Maps are then randomly shuffled between the 2 groups
-    
      
-     
    • Pair-wise in the paired test, just the order of the 
-     conditions can be swapped,
      
-     
    • Any redistribution for the unpaired test, just to 
-     make 2 groups.
    
-    
  • Means of the maps of the two new groups is computed,
    
-    
  • Then the dissimilarity of the means is tested against the 
-	original dissimilarity of the 2 groups.
    
-   

-  

-   Sign for the t-test and the Randomization

-  

-   In case you need to know which of the two conditions was above / 
-   greater than the other one, you need to know how the subtraction was 
-   performed during the tests.

-  

-   Cartool always compute differences as  group 1 - group 2.

-  

-   So f.ex. a positive t-value at a given Time Frame means group 2 is 
-   below / less than group 1 at that moment.

-  

-   Positive Data and its implications

-  

-   Selecting Positive Data 
-   means data should not be re-centered to their average values in any 
-   of the computations. Of course don't select this if the data are 
-   signed, it will not convert them at all!

-  

-    

-  

-   The following formula will therefore skip the average reference subtraction:

-  
    
-   
  • 
-   
    
-    GFP (Global Field Power), which actually becomes RMS (Root Mean Square)
    
-   
  • 
-   
    
-    Dissimilarity
    
-   

-  

-    

-  

-   Some formula still subtract the average reference, to be 
-   consistent with pattern matching techniques:

-  
    
-   
  • 
-   
    
-    Correlation
    
-   
  • 
-   
    
-    Explained Variance
    
-   
  • 
-   
    
-    Normalization of maps
    
-   

-  

-   Statistics - Results

-  

-   Directory structure

-  

-   First of all, a directory structure is created as follow:

-  
    
-   
  • 
-   
    
-    First a general directory, named after the Base
-     File Name
    
-   
  • 
-   
    
-    Then, each test will create its own sub-directory, named after 
-    the test itself, f.ex. "Paired.tTest" or "Unpaired.TAnova".
    
-   

-  

-   This way, results are not mixed across different tests, and you can 
-   later run a specific test without erasing the previous results of 
-   other tests.

-  

-   Result files

-  

-   The files within these directories, one for each type of test, are 
-   the following:

-  
    
-   
  • 
-   
    
-    A verbose file .vrb,
-     with all the parameters being used.
    
-   
    
-    It optionally contains the results in a textual form, if there was no 
-    time dimension in the data, or if it was only 1 time frame long. In 
-    this case there is an array with the following columns:
    
-   
      
-    
    • 
-    
      
-     Variable name
      
-     
    • P-value
      
-     
    • Number of data actually used for the computation 
-     (paired case: 2 * number of subjects used)
      
-     
    • t-value, in the t-test case
      
-     
    • Degrees of freedom, in the t-test case
      
-    
    
-   
    
-     
    
-   
  • 
-   
    
-    A .p.ep 
-    file for the P-values, actually (1 - P). There is a 
-    color coding for the P-value, from ( 1 - P ) = 0 / grey to ( 1 - P ) 
-    = 1 / red. The following examples show the full P-values, first 
-    without Bonferroni and no clipping of P, then the P-values after 
-    Bonferroni and clipping, when testing all electrodes:
    
-   
    
-    
    
-   
    
-     
    
-   

-  

-   For the t-test, you have this additional file:

-  
    
-   
  • 
-   
    
-    A .t.ep 
-    file for the t-values:
    
-   
    
-    
    
-   

-  

-    

-  

-   When testing Fitting variables, you 
-   have this additional file:

-  
    
-   
  • 
-   
    
-    A .p.data 
-    file, with the P-values ( 1 - P ) for each variable (vertical axis), 
-    and for each map (horizontal axis). F.ex. before and after clipping 
-    the P-value:
    
-   
    
-    
    
-   

-  

-    

-  

-   If the Save
-    Intermediate Results option has been selected, you will get 
-   these more files:

-  
    
-   
  • 
-   
    
-    Unpaired and Paired t-test, for each group:
    
-   
      
-    
    • 
-    
      
-     The Mean in .Group#.Mean.ep
      
-    
    • 
-    
      
-     The Standard Error in .Group#.SE.ep
      
-    
    • 
-    
      
-     A big matrix with all the subjects one after the other, plus 
-     the Mean and SE in .Group#.Subjects.sef
      
-    
    
-   
  • 
-   
    
-    Unpaired t-test only:
    
-   
      
-    
    • 
-    
      
-     The Difference of the mean in .Delta.Mean.ep
      
-    
    • 
-    
      
-     The Joint Standard Error (of both groups) in .Delta.SE.ep
      
-    
    
-   
  • 
-   
    
-    Paired t-test only:
    
-   
      
-    
    • 
-    
      
-     The Mean of the difference in .Delta.Mean.ep
      
-    
    • 
-    
      
-     The Standard Error of the difference in .Delta.SE.ep
      
-    
    
-   
  • 
-   
    
-    Unpaired and Paired TAnova:
    
-   
      
-    
    • 
-    
      
-     The Dissimilarity of the mean maps in .TAnova.Dis.ep
      
-    
    
-   

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    
+         

+             TAnova (Topographic Anova) method
+         

+         

+             The following randomization procedure is applied (for each time frame):
+         

+         
    
+             
  • 
+                 
    
+                     All the maps are average referenced, then normalized,
    
+             
  • 
+                 Maps are then randomly shuffled between the 2 groups
+                 
      
+                     
    • 
+                         Pair-wise in the paired test, just the order of the
+                         conditions can be swapped,
      
+                     
    • 
+                         Any redistribution for the unpaired test, just to
+                         make 2 groups.
+                 
    
+             
  • Means of the maps of the two new groups is computed,
    
+             
  • 
+                 Then the dissimilarity of the means is tested against the
+                 original dissimilarity of the 2 groups.
    
+         

+         

+             Sign for the t-test and the Randomization
+         

+         

+             In case you need to know which of the two conditions was above /
+             greater than the other one, you need to know how the subtraction was
+             performed during the tests.
+         

+         

+             Cartool always compute differences as  group 1 - group 2.
+         

+         

+             So f.ex. a positive t-value at a given Time Frame means group 2 is
+             below / less than group 1 at that moment.
+         

+         

+             Positive Data and its implications
+         

+         

+             Selecting Positive Data
+             means data should not be re-centered to their average values in any
+             of the computations. Of course don't select this if the data are
+             signed, it will not convert them at all!
+         

+         

+              
+         

+         

+             The following formula will therefore skip the average reference subtraction:
+         

+         
    
+             
  • 
+                 
    
+                     GFP (Global Field Power), which actually becomes RMS (Root Mean Square)
+                 
    
+             
  • 
+                 
    
+                     Dissimilarity
+                 
    
+         

+         

+              
+         

+         

+             Some formula still subtract the average reference, to be
+             consistent with pattern matching techniques:
+         

+         
    
+             
  • 
+                 
    
+                     Correlation
+                 
    
+             
  • 
+                 
    
+                     Explained Variance
+                 
    
+             
  • 
+                 
    
+                     Normalization of maps
+                 
    
+         

+         

+             Statistics - Results
+         

+         

+             Directory structure
+         

+         

+             First of all, a directory structure is created as follow:
+         

+         
    
+             
  • 
+                 
    
+                     First a general directory, named after the 
+                         Base
+                         File Name
+                     
+                 
    
+             
  • 
+                 
    
+                     Then, each test will create its own sub-directory, named after
+                     the test itself, f.ex. "Paired.tTest" or "Unpaired.TAnova".
+                 
    
+         

+         

+             This way, results are not mixed across different tests, and you can
+             later run a specific test without erasing the previous results of
+             other tests.
+         

+         

+             Result files
+         

+         

+             The files within these directories, one for each type of test, are
+             the following:
+         

+         
    
+             
  • 
+                 
    
+                     A verbose file .vrb,
+                     with all the parameters being used.
+                 
    
+                 
    
+                     It optionally contains the results in a textual form, if there was no
+                     time dimension in the data, or if it was only 1 time frame long. In
+                     this case there is an array with the following columns:
+                 
    
+                 
      
+                     
    • 
+                         
      
+                             Variable name
      
+                     
    • P-value
      
+                     
    • 
+                         Number of data actually used for the computation
+                         (paired case: 2 * number of subjects used)
      
+                     
    • t-value, in the t-test case
      
+                     
    • Degrees of freedom, in the t-test case
      
+                 
    
+                 
    
+                      
+                 
    
+             
  • 
+                 
    
+                     A .p.ep
+                     file for the P-values, actually (1 - P). There is a
+                     color coding for the P-value, from ( 1 - P ) = 0 / grey to ( 1 - P )
+                     = 1 / red. The following examples show the full P-values, first
+                     without Bonferroni and no clipping of P, then the P-values after
+                     Bonferroni and clipping, when testing all electrodes:
+                 
    
+                 
    
+                     
+                 
    
+                 
    
+                      
+                 
    
+         

+         

+             For the t-test, you have this additional file:
+         

+         
    
+             
  • 
+                 
    
+                     A .t.ep
+                     file for the t-values:
+                 
    
+                 
    
+                     
+                 
    
+         

+         

+              
+         

+         

+             When testing Fitting variables, you
+             have this additional file:
+         

+         
    
+             
  • 
+                 
    
+                     A .p.data
+                     file, with the P-values ( 1 - P ) for each variable (vertical axis),
+                     and for each map (horizontal axis). F.ex. before and after clipping
+                     the P-value:
+                 
    
+                 
    
+                     
+                 
    
+         

+         

+              
+         

+         

+             If the 
+                 
+                     Save
+                     Intermediate Results
+                 
+              option has been selected, you will get
+             these more files:
+         

+         
    
+             
  • 
+                 
    
+                     Unpaired and Paired t-test, for each group:
+                 
    
+                 
      
+                     
    • 
+                         
      
+                             The Mean in .Group#.Mean.ep
+                         
      
+                     
    • 
+                         
      
+                             The Standard Error in .Group#.SE.ep
+                         
      
+                     
    • 
+                         
      
+                             A big matrix with all the subjects one after the other, plus
+                             the Mean and SE in .Group#.Subjects.sef
+                         
      
+                 
    
+             
  • 
+                 
    
+                     Unpaired t-test only:
+                 
    
+                 
      
+                     
    • 
+                         
      
+                             The Difference of the mean in .Delta.Mean.ep
+                         
      
+                     
    • 
+                         
      
+                             The Joint Standard Error (of both groups) in .Delta.SE.ep
+                         
      
+                 
    
+             
  • 
+                 
    
+                     Paired t-test only:
+                 
    
+                 
      
+                     
    • 
+                         
      
+                             The Mean of the difference in .Delta.Mean.ep
+                         
      
+                     
    • 
+                         
      
+                             The Standard Error of the difference in .Delta.SE.ep
+                         
      
+                 
    
+             
  • 
+                 
    
+                     Unpaired and Paired TAnova:
+                 
    
+                 
      
+                     
    • 
+                         
      
+                             The Dissimilarity of the mean maps in .TAnova.Dis.ep
+                         
      
+                 
    
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+     

  
 
\ No newline at end of file
diff --git a/docs/ReferenceGuide/coregistering-electrodes-to-mri.html b/docs/ReferenceGuide/coregistering-electrodes-to-mri.html
index 534ce387..74a7d005 100644
--- a/docs/ReferenceGuide/coregistering-electrodes-to-mri.html
+++ b/docs/ReferenceGuide/coregistering-electrodes-to-mri.html
@@ -26,571 +26,741 @@
 }
 
  
- 
-  

-   Electrodes Coregistration to MRI

-  

-    

-  

-   This toolbox helps the user to interactively coregister electrodes on 
-   a full head MRI. This is usually a required step before
-   building inverse 
-   matrices.

-  

-    

-  

-   Electrodes Coregistration Dialog

-  

-   Technical points & hints

-  

-       Actions

-  

-       Glueing electrodes

-  

-       Recommended sequence for coregistration

-  

-   Results

-  

-   Electrodes Coregistration
-   Dialog

-  

-   Called from the  Tools
-    | Electrodes Coordinates and Solution Points | Coregistering Electrodes to 
-   MRI Head  menu, the following dialog appears:

-  

-   

-  

-    

-   
-       
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-    
-     
-     
-    
-   

-	 
Presets

-		   		
-	 
There are currently only 2 presets:

-	 
    
-		 
  • Starting from scratch: it will guess an initial 
-		 scaling and position before starting
    • 
-		 
  • Reloading the electrodes coordinates as is: skip 
-		 the guess and start straight away
    • 
-	 

-		   

-	 
Input Files

-		   		
-	 
 

-		   

-	 
Source XYZ file:

-		   		
-	 
The electrodes coordinates file to be coregistered.

-		   

-	 
Target MRI Head file:

-		   		
-	 
The target MRI.

-		   

-	 
Actions

-		   		
-	 
Once everything is opened up, you can start to geometrical update the 
-	 electrodes geometry with these actions:

-		   

-	 
Rescale

-		   		
-	 
Rescales the X, Y or
-	 Z axis, or all of them (Global).

-		   

-	 
Translate

-		   		
-	 
Translates in the X, Y or Z 
-	 axis.

-		   

-	 
Rotate

-		   		
-	 
Rotates the X, Y or Z 
-	 axis. 

-		   

-	 
Magic

-		   		
-	 
Glueing the electrodes onto the 
-	 scalp surface.

-		   

-	 
Historic

-		   		
-	 
 

-		   

-	 
Undo Last

-		   		
-	 
Goes one step backward into the history of transforms.

-		   

-	 
Redo Last

-		   		
-	 
Goes one step forward into the history of transforms.

-		   

-	 
Undo All

-		   		
-	 
Undo all. Note that the history is still 
-	 available, so you can move forward again if you wish...

-		   

-	 
Redo All

-		   		
-	 
Redo all.

-		   

-	 
Clear All

-		   		
-	 
Undo all then erase all history. Guess 
-	 you have to be a little cautious before doing that, don't you?

-		   

-	 
Output

-		   		
-	 
 

-		   

-	 
Output Base File Prefix:

-				
-	 
Directory and prefix used for all output files.

-		

-  

-   Electrodes Coregistration -  Technical 
-   points & hints

-  

-   Actions

-  

-   Axis considerations

-  

-   Before applying a transform step, you have to pay attention toward 
-   which directions the X, Y and Z axis are pointing to. On any 
-   display, the X axis is 
-   colored red, the Y axis, green and the Z axis, blue.

-  

-   For the usual 'RAS' orientation case (or MNI orientation), we have:

-  
    
-	  
  • X pointing toward the Right side
    • 
-	  
  • Y pointing toward the Anterior part
    • 
-	  
  • Z pointing toward the Superior part
    • 
-  

-  

-    

-  

-   Most actions need an axis specified to be performed. F.ex. you can
-   Rotate around the X axis (RX) or Translate in the Y 
-   axis (TY). En plus of the axis, the
-   direction of the action should be specified, like 
-   Translate Y forward (TY+) or Translate Y backward (TY-). 
-   Hence the axis + sign butons. Just try and see,
-   in any case you can always undo your last step!

-  

-    

-  

-   Actions considerations

-  
    
-	  
  • Rescaling is equivalent to "stretching" or "compressing"; translating 
-	  to shifting position; and rotating to turning around.
    • 
-	  
  • The way the toolbox works is by applying small incremental 
-	  transforms, one at a time.
    The increment will be small if you click sporadically on a 
-	  button, and will increase with faster presses.
    • 
-	  
  • The Glueing action is 
-	  definitely appart from all the other operations, for many reasons. First 
-	  it is a non-linear 
-	  operation (and can not be represented in a 4x4 homegenous transform). 
-	  Second, it is very radical and is best done at the very end of the 
-	  coregistration.
    • 
-	  
  • You can undo and redo any number of steps to assert your whole 
-	  transform (or if you are a little bit geeky and enjoy tiny 
-	  pleasures like the replay).
    • 
-  

-  

-    

-  

-   Glueing electrodes

-  

-   Glueing the electrodes on 
-   the surface projects them to the closest point on the surface
-    of the scalp. This forces the electrodes to have the exact 
-   shape of the head, and the exact distances to the brain, 
-   which is a good thing when computing 
-   Inverse Matices.

-  

-    

-  

-   Glueing can also save the day, too, by un-spherizing a spherical 
-   template electrodes set back to a real head shape. However, note 
-   that this is still an approximation: it is quite unlikely that the 
-   un-spherization function used here will perfectly revert the spherization function used on the first hand! So you 
-   can end up with some geometrical distortions that can bias 
-   all your inverse solutions!

-  

-   One solution to this problem would be to 
-   compute a real template 
-   of your electrodes set. Un-spherize only if you can not do otherwise!

-  

-    

-  

-   Glueing might not be a good idea, if your electrodes set covers 
-   the neck / jaws, but the target MRI has been clipped at ear / 
-   cerebellum level. That is, your electrodes set have a wider 
-   coverage than the available MRI. The electrodes below the missing 
-   part of the MRI will be simply rescaled, so you could end up with a 
-   sort of discontinuity at the border. Visually check this, it can be 
-   either tolerable or a disaster, this is up to you at this point...

-  

-    

-  

-   Glueing shouldn't be done if the MRI appears to have some sorts 
-   of holes on the surface, for whatever reasons (MRI artifact, or a real 
-   hole in the head...). Should this be the case, the "glued" 
-   electrodes could end up inside the head, which is a real concern 
-   for the inverse solutions, to say the least! In this case, simply 
-   adjust as much as you can with translations / rotations / scalings 
-   and avoid the glueing step.

-  

-    

-  

-   An example of a real electrodes set successfully glued to its 
-   corresponding real head, best case scenario:

-  
    
-   
    
-    
    
-   

-  

-   An example of spherical electrodes set successfully glued to a real
-    head, not ideal but should work:

-  
    
-   
    
-    
    
-   

-  

-   An example of spherical electrodes set successfully glued to a template
-    head (MNI), not ideal but should work: :

-  
    
-   
    
-    
    
-   

-  

-   An example of spherical electrodes set potentially problematic 
-   due to the electrodes floating in the air below the MRI cut, try 
-   to avoid:

-  
    
-   
    
-    
    
-   

-  

-   An example of a real electrodes set with a corrupted MRI 
-   (irregular surface), before and after gluing, showing some electrodes 
-   landed inside the head, so avoid gluing here:

-  
    
-   
    
-    
    
-   

-  

-    

-  

-   Recommended sequence for coregistration

-  

-   Your MRI should be correctly oriented & origin properly set before 
-   performing any coregistration! 
-   Re-align & set the origin beforehand if needed.

-  

-    

-  

-   Once the dialog is all set and the display opens up, here is what a typical sequence of operations 
-   looks like:

-  

-    

-   
-       
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-   

-	 

-		   		
-	 
Starting from the initial guess of Cartool (centering, scaling)

-	 
We are going to work only on the side view for the moment

-		   

-	 

-		   		
-	 
Translation Y- (back)

-		   

-	 
 

-		   		
-	 
Translation Z- (down)

-		   

-	 
 

-		   		
-	 
Global rescaling (shrinking)

-	 
It might be necessary to repeat the last 3 steps - or not

-		   

-	 
  

-		   		
-	 
Rotation X-

-		   

-	 
  

-		   		
-	 
Translation Z-

-		   

-	 
 

-		   		
-	 
Rotation X+

-		   

-	 
  

-		   		
-	 
Turning display now & checking the electrodes now around the 
-	 eyes

-		   

-	 
  

-		   		
-	 
Rotation X+

-	 
Now that we see the face, we can adjust the rotation. Don't forget that 
-	 eyebrows can not be seen on the MRI and that you certainly didn't put 
-	 electrodes on them!

-		   

-	 
 

-		   		
-	 
Turning display & checking around the ears

-		   

-	 

-		   		
-	 
Scale Z+ (expand top-down)

-		   

-	 

-		   		
-	 
Scale Y- (shrink front-back)

-		   

-	 

-		   		
-	 
Checking left-right

-		   

-	 

-		   		
-	 
Scale X+ (expand left-right)

-	 
Tiny adjustment here

-		   

-	 

-		   		
-	 
Final check?

-		   

-	 

-		   		
-	 
Glueing electrodes!

-	 
This should be done at the end only, although you can try during the 
-	 whole process to guess how the projected electrodes are going to land.

-		   

-  

-    

-  

-   A few comments:

-  
    
-	  
  • No X (left-right) translation, nor Y rotation, 
-	  nor Z rotation were ever needed during the 
-	  coregistration! This is due to the fact that both the MRI and the 
-	  electrodes (should) have been optimally re-centered, which sets 
-	  these 3 parameters. You should not have to adjust these in most cases. It 
-	  could be necessary for non-aligned input MRIs.
    • 
-	  
  • Check that the glueing does not send any electrodes in bad 
-	  places: inside the head, inside a cavity, or even on the ear - 
-	  anything geometrically non-realistic. Try tiny adjustments while 
-	  remaining "glued" to fix the problem. If this does not help, 
-	  either plainly give up on the glueing part, or apply the glueing and edit 
-	  manually the faulty electrodes once the file has been saved.
    • 
-	  
  • If the head has been clipped quite high and the parts 
-	  below the nose level is missing (MNI template, we look at you), Cartool 
-	  will normally skip the glueing below this "guillotine" limit. 
-	  Again, try your best without the glueing for these electrodes,
-	  glue and check the whole electrode setup looks 
-	  reasonable.
    • 
-	  
  • As can be seen on the sequence above, the full 257 electrodes 
-	  were being coregistered. Although we might use a subset later, 
-	  like 204 electrodes, using all the geometrical information 
-	  available improves the reliability of the coregistration. It is 
-	  quite easy to remove the few useless electrodes after the 
-	  coregistration.
    • 
-	  
  • Consider taking a picture of the subjects with the net on. 
-	  Using these pictures could help a lot building individual models, 
-	  especially if different people are involved during the recording and the 
-	  modelling. By experience, peoples / labs have a tendency to set the 
-	  electrodes a tiny bit differently, so having actual visual cues will 
-	  definitely help. This applies even more so when dealing with 
-	  animals recording / models.
    • 
-  

-  

-    Electrodes Coregistration - Results

-  

-   Coregistering generates the following output files:

-  
    
-   
  • 
-   
    
-    All files will start with the provided output base file name, 
-	including directory part;
    
-   
  • 
-   
    
-    A .xyz file for the 
-    coregistered electrodes;
    
-   
  • 
-   
    
-    A .vrb verbose file.
    
-   

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    
+ 
+     

+         

+             Electrodes Coregistration to MRI
+         

+         

+              
+         

+         

+             This toolbox helps the user to 
+                 interactively coregister electrodes on
+                 a full head MRI
+             . This is usually a required step before
+             
+                 building inverse
+                 matrices
+             .
+         

+         

+              
+         

+         

+             Electrodes Coregistration Dialog
+         

+         

+             Technical points & hints
+         

+         

+                 Actions
+         

+         

+                 Glueing electrodes
+         

+         

+                 Recommended sequence for coregistration
+         

+         

+             Results
+         

+         

+             Electrodes Coregistration
+             Dialog
+         

+         

+             Called from the  
+                 
+                     Tools
+                     | Electrodes Coordinates and Solution Points | Coregistering Electrodes to
+                     MRI Head
+                 
+               menu, the following dialog appears:
+         

+         

+             
+         

+         

+              
+         

+         
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+         

+                     
Presets

+                 		
+                     
There are currently only 2 presets:

+                     
    
+                         
  • 
+                             Starting from scratch: it will guess an initial
+                             scaling and position before starting
+                         
    • 
+                         
  • 
+                             Reloading the electrodes coordinates as is: skip
+                             the guess and start straight away
+                         
    • 
+                     

+                 

+                     
Input Files

+                 		
+                     
 

+                 

+                     
Source XYZ file:

+                 		
+                     
The electrodes coordinates file to be coregistered.

+                 

+                     
Target MRI Head file:

+                 		
+                     
The target MRI.

+                 

+                     
Actions

+                 		
+                     

+                         Once everything is opened up, you can start to geometrical update the
+                         electrodes geometry with these actions:
+                     

+                 

+                     
Rescale

+                 		
+                     

+                         Rescales the X, Y or
+                         Z axis, or all of them (Global).
+                     

+                 

+                     
Translate

+                 		
+                     

+                         Translates in the X, Y or Z
+                         axis.
+                     

+                 

+                     
Rotate

+                 		
+                     

+                         Rotates the X, Y or Z
+                         axis. 
+                     

+                 

+                     
Magic

+                 		
+                     

+                         Glueing the electrodes onto the
+                         scalp surface.
+                     

+                 

+                     
Historic

+                 		
+                     
 

+                 

+                     
Undo Last

+                 		
+                     
Goes one step backward into the history of transforms.

+                 

+                     
Redo Last

+                 		
+                     
Goes one step forward into the history of transforms.

+                 

+                     
Undo All

+                 		
+                     

+                         Undo all. Note that the 
+                             history is still
+                             available
+                         , so you can move forward again if you wish...
+                     

+                 

+                     
Redo All

+                 		
+                     
Redo all.

+                 

+                     
Clear All

+                 		
+                     

+                         Undo all then erase all history. Guess
+                         you have to be a little cautious before doing that, don't you?
+                     

+                 

+                     
Output

+                 		
+                     
 

+                 

+                     
Output Base File Prefix:

+                 		
+                     
Directory and prefix used for all output files.

+                 

+         

+             Electrodes Coregistration -  Technical
+             points & hints
+         

+         

+             Actions
+         

+         

+             Axis considerations
+         

+         

+             Before applying a transform step, 
+                 you have to pay attention toward
+                 which directions the X, Y and Z axis are pointing to
+             . On any
+             display, the X axis is
+             colored red, the Y axis, green and the Z axis, blue.
+         

+         

+             For the usual 'RAS' orientation case (or MNI orientation), we have:
+         

+         
    
+             
  • X pointing toward the Right side
    • 
+             
  • Y pointing toward the Anterior part
    • 
+             
  • Z pointing toward the Superior part
    • 
+         

+         

+              
+         

+         

+             Most actions need an axis specified to be performed. F.ex. you can
+             Rotate around the X axis (RX) or 
+                 Translate in the Y
+                 axis (TY)
+             . En plus of the axis, the
+             direction of the action should be specified, like 
+                 Translate Y forward (TY+)
+              or Translate Y backward (TY-).
+             Hence the axis + sign butons. Just try and see,
+             in any case you can always undo your last step!
+         

+         

+              
+         

+         

+             Actions considerations
+         

+         
    
+             
  • 
+                 Rescaling is equivalent to "stretching" or "compressing"; translating
+                 to shifting position; and rotating to turning around.
+             
    • 
+             
  • 
+                 The way the toolbox works is by applying 
+                     small incremental
+                     transforms
+                 , one at a time.
    The increment will be small if you click sporadically on a
+                 button, and will increase with faster presses.
+             
    • 
+             
  • 
+                 The Glueing action is
+                 definitely appart from all the other operations, for many reasons. First
+                 it is a non-linear
+                 operation (and can not be represented in a 4x4 homegenous transform).
+                 Second, it is very radical and is best done at the very end of the
+                 coregistration.
+             
    • 
+             
  • 
+                 You can 
+                     undo and redo any number of steps to assert your whole
+                     transform
+                  (or if you are a little bit geeky and enjoy tiny
+                 pleasures like the replay).
+             
    • 
+         

+         

+              
+         

+         

+             Glueing electrodes
+         

+         

+             Glueing the electrodes on
+             the surface projects them to the closest point on the 
+                 surface
+                 of the scalp
+             . This forces the electrodes to have the 
+                 exact
+                 shape of the head
+             , and the exact distances to the brain,
+             which is a good thing when 
+                 computing
+                 Inverse Matices
+             .
+         

+         

+              
+         

+         

+             Glueing can also save the day, too, by 
+                 un-spherizing a spherical
+                 template electrodes set
+              back to a real head shape. However, note
+             that this is still an approximation: it is quite unlikely that the
+             un-spherization function used here will perfectly revert the spherization function used on the first hand! So you
+             can end up with some geometrical distortions that can 
+                 bias
+                 all your inverse solutions
+             !
+         

+         

+             One solution to this problem would be to 
+                 compute a real template
+             
+             of your electrodes set. Un-spherize only if you can not do otherwise!
+         

+         

+              
+         

+         

+             Glueing might not be a good idea, if your electrodes set covers
+             the neck / jaws, but the target MRI has been clipped at ear /
+             cerebellum level. That is, your electrodes set have a 
+                 wider
+                 coverage than the available MRI
+             . The electrodes below the missing
+             part of the MRI will be simply rescaled, so you could end up with a
+             sort of discontinuity at the border. Visually check this, it can be
+             either tolerable or a disaster, this is up to you at this point...
+         

+         

+              
+         

+         

+             Glueing shouldn't be done if the MRI appears to have some sorts
+             of holes on the surface, for whatever reasons (MRI artifact, or a real
+             hole in the head...). Should this be the case, the "glued"
+             electrodes could end up inside the head, which is a real concern
+             for the inverse solutions, to say the least! In this case, simply
+             adjust as much as you can with translations / rotations / scalings
+             and avoid the glueing step.
+         

+         

+              
+         

+         

+             An example of a real electrodes set successfully glued to its
+             corresponding real head, best case scenario:
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+             An example of spherical electrodes set successfully glued to a 
+                 real
+                 head
+             , not ideal but should work:
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+             An example of spherical electrodes set successfully glued to a 
+                 template
+                 head
+              (MNI), not ideal but should work: :
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+             An example of spherical electrodes set potentially problematic
+             due to the electrodes floating in the air below the MRI cut, 
+                 try
+                 to avoid
+             :
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+             An example of a real electrodes set with a corrupted MRI
+             (irregular surface), before and after gluing, showing some electrodes
+             landed inside the head, so avoid gluing here:
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+              
+         

+         

+             Recommended sequence for coregistration
+         

+         

+             
+                 Your MRI should be correctly oriented & origin properly set before
+                 performing any coregistration!
+              
+                 Re-align & set the origin
+              beforehand if needed.
+         

+         

+              
+         

+         

+             Once the dialog is all set and the display opens up, here is what a typical sequence of operations
+             looks like:
+         

+         

+              
+         

+         
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+         

+                     

+                 		
+                     
Starting from the initial guess of Cartool (centering, scaling)

+                     
We are going to work only on the side view for the moment

+                 

+                     

+                 		
+                     
Translation Y- (back)

+                 

+                     
 

+                 		
+                     
Translation Z- (down)

+                 

+                     
 

+                 		
+                     
Global rescaling (shrinking)

+                     
It might be necessary to repeat the last 3 steps - or not

+                 

+                     
  

+                 		
+                     
Rotation X-

+                 

+                     
  

+                 		
+                     
Translation Z-

+                 

+                     
 

+                 		
+                     
Rotation X+

+                 

+                     
  

+                 		
+                     

+                         Turning display now & checking the electrodes now 
+                             around the
+                             eyes
+                         
+                     

+                 

+                     
  

+                 		
+                     
Rotation X+

+                     

+                         Now that we see the face, we can adjust the rotation. Don't forget that
+                         eyebrows can not be seen on the MRI and that you certainly didn't put
+                         electrodes on them!
+                     

+                 

+                     
 

+                 		
+                     
Turning display & checking around the ears

+                 

+                     

+                 		
+                     
Scale Z+ (expand top-down)

+                 

+                     

+                 		
+                     
Scale Y- (shrink front-back)

+                 

+                     

+                 		
+                     
Checking left-right

+                 

+                     

+                 		
+                     
Scale X+ (expand left-right)

+                     
Tiny adjustment here

+                 

+                     

+                 		
+                     
Final check?

+                 

+                     

+                 		
+                     
Glueing electrodes!

+                     

+                         This should be done at the end only, although you can try during the
+                         whole process to guess how the projected electrodes are going to land.
+                     

+                 

+         

+              
+         

+         

+             A few comments:
+         

+         
    
+             
  • 
+                 No X (left-right) translation, nor Y rotation,
+                 nor Z rotation were ever needed during the
+                 coregistration! This is due to the fact that both the 
+                     MRI and the
+                     electrodes (should) have been optimally re-centered
+                 , which sets
+                 these 3 parameters. You should not have to adjust these in most cases. It
+                 could be necessary for non-aligned input MRIs.
+             
    • 
+             
  • 
+                 Check that the glueing does not send any 
+                     electrodes in bad
+                     places: inside the head, inside a cavity, or even on the ear
+                  -
+                 anything geometrically non-realistic. Try 
+                     tiny adjustments while
+                     remaining "glued"
+                  to fix the problem. If this does not help,
+                 either plainly give up on the glueing part, or apply the glueing and edit
+                 manually the faulty electrodes once the file has been saved.
+             
    • 
+             
  • 
+                 If the head has been clipped quite high and the parts
+                 below the nose level is missing (MNI template, we look at you), Cartool
+                 will normally skip the glueing below this "guillotine" limit.
+                 Again, try your best without the glueing for these electrodes,
+                 
+                     glue and check the whole electrode setup looks
+                     reasonable
+                 .
+             
    • 
+             
  • 
+                 As can be seen on the sequence above, the 
+                     full 257 electrodes
+                     were being coregistered
+                 . Although we might use a subset later,
+                 like 204 electrodes, 
+                     using all the geometrical information
+                     available improves the reliability of the coregistration
+                 . It is
+                 quite easy to remove the few useless electrodes after the
+                 coregistration.
+             
    • 
+             
  • 
+                 Consider taking a picture of the subjects with the net on.
+                 Using these pictures could help a lot building individual models,
+                 especially if different people are involved during the recording and the
+                 modelling. By experience, peoples / labs have a tendency to set the
+                 electrodes a tiny bit differently, so having actual visual cues will
+                 definitely help. This applies even more so when dealing with 
+                     animals recording / models
+                 .
+             
    • 
+         

+         

+              Electrodes Coregistration - Results
+         

+         

+             Coregistering generates the following output files:
+         

+         
    
+             
  • 
+                 
    
+                     All files will start with the provided output base file name,
+                     including directory part;
+                 
    
+             
  • 
+                 
    
+                     A .xyz file for the
+                     coregistered electrodes;
+                 
    
+             
  • 
+                 
    
+                     A .vrb verbose file.
+                 
    
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+     

  
 
\ No newline at end of file
diff --git a/docs/ReferenceGuide/creating-rois.html b/docs/ReferenceGuide/creating-rois.html
index abca0883..0b853a1a 100644
--- a/docs/ReferenceGuide/creating-rois.html
+++ b/docs/ReferenceGuide/creating-rois.html
@@ -8,1106 +8,1480 @@
 }
 
  
- 
-  

-   Creating ROIs

-  

-    

-  

-   This page is about creating the .rois files,
-    the preliminary step before actually being able to apply the rois
-    calculus itself. The .rois files are actually 
-   just groups of indexes (of tracks, electrodes, solution points, or whatever).

-  

-   Creating rois can be done either automatically or through user
-    interaction.

-  

-    

-  

-   Automatic creation of ROIs

-  
-  

-   Interactive creation of ROIs

-  
-  

-   Automatic creation of ROIs

-  

-   This way of generating .rois files 
-   is done by looking for the intersection of the solution points 
-   with a volume mask. The generated ROIs can then be used either 
-   with the Inverse Solution display,
-    the Statistics or the Export 
-   of RIS files.

-  

-   Three options are available:

-  
    
-   
  • 
-   
    
-    specifying a set of Talairach regions,
    
-   
  • 
-   
    
-    scanning the AAL 
-    volume mask,
    
-   
  • 
-   
    
-    scanning any arbitrary volume mask that contains some region labels.
    
-   

-  

-    

-  

-   Automatic creation of ROIs from 
-   Talairach regions

-  

-   This automatic generation needs a solution
-    points file that has a Talairach
-    transformation function attached to it. If this 
-   function is available, you can simply provide a text file naming 
-   some Talaraich regions, and Cartool will create the groups of 
-   solution points that fit within each of the named regions.

-  

-    

-  

-   Called from the Tools
-    | Creating Rois menu, the following dialog appears:

-  

-   

-    

-   

-  

-   Note that only the relevant parameters to the current processing 
-   are being listed here:

-  

-   

-    
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-    

-       

-        Input Files

-       

-         

-       

-        EEG / RIS / XYZ / SP file

-       

-        In our case, provide a solution
-         points file, with Talaraich
-         abilities. 

-       

-        Use Drag & Drop to save time!

-       

-        ROIs Volume file (optional):

-       

-        You can optionally provide a MRI file 
-        containing a grey matter / brain mask.

-       

-        This MRI will solely be used for generating another mask MRI, with 
-        the labels generated from the specified Talairach regions.

-       

-        ROIs Labels file (optional):

-       

-        (not relevant here, Talairach names are hard-encoded in Cartool).

-       

-        Processing Mode:

-       

-        Select Automatic

-       

-        Automatic Mode:

-       

-         

-       

-        SPs Intersecting a ROIS Volume:

-       

-        Select Talairach ROIs

-       

-        Generating ROIs (optional text file):

-       

-        Give a file with the Talairach regions you would like to generate.

-       

-        This file is actually mandatory for the Talairach case...

-       

-        See below for the (simplistic) syntax 
-        of the file.

-       

-        Output

-       

-         

-       

-        Output Base File Name:

-       

-        Specifies a basis for all the file names that will be 
-        generated (main directory, common file name).

-       

-        Options:

-       

-         

-       

-        Open File(s) Upon Completion

-       

-        What it says...

-   

-  

-    

-  

-   ROIs from Talairach - Technical points 
-   & hints

-  

-   Naming convention

-  

-   The text file containing the named Talairach regions follow a very 
-   simple syntax:

-  
    
-   
  • 
-   
    
-    each line is a region,
    
-   
  • 
-   
    
-    optionally, the line can begin with either the Right or Left keyword,
    
-   
  • 
-   
    
-    use one or more of the known Talairach labels 
-    listed below, separated by a comma "," . If more 
-    than one label is listed, this means the intersection of the 
-    regions will be used.
    
-   

-  

-    

-  

-   As usual (!) Cartool tries to ease your work, so when specifying the Right 
-   or Left keywords, what it does is gathering (adding together) 
-   all the labels which holds this keyword, silently compounding a whole 
-   left or right structure. Then only it will be intersected with the 
-   named Talairach region that follows. It is even possible to just 
-   specify Left or Right on a line, just to see all the structures on 
-   the left and right (respectively).

-  

-    

-  

-   Example of valid namings:
Left Cerebrum
Right Cerebrum
Left Posterior Lobe
Right Posterior Lobe
Left Occipital Lobe, Middle Occipital Gyrus
Left Occipital Lobe, Middle Occipital Gyrus, Gray Matter

-   Recognized Talairach names

-  

-   Here are all the labels Cartool will recognize:
Label 1
Inter-Hemispheric
Left Cerebrum
Right Cerebrum
Right Cerebellum
Right Brainstem
Left Brainstem
Left Cerebellum
Label 2
Posterior Lobe
Anterior Lobe
Frontal-Temporal Space
Limbic Lobe
Medulla
Pons
Midbrain
Sub-lobar
Occipital Lobe
Temporal Lobe
Parietal Lobe
Frontal Lobe
Label 3
Posterior Cingulate
Anterior Cingulate
Subcallosal Gyrus
Sub-Gyral
Transverse Temporal Gyrus
Uncus
Rectal Gyrus
Fusiform Gyrus
Inferior Occipital Gyrus
Inferior Temporal Gyrus
Insula
Parahippocampal Gyrus
Lingual Gyrus
Middle Occipital Gyrus
Orbital Gyrus
Middle Temporal Gyrus
Superior Temporal Gyrus
Superior Occipital Gyrus
Precentral Gyrus
Inferior Frontal Gyrus
Cuneus
Angular Gyrus
Supramarginal Gyrus
Cingulate Gyrus
Inferior Parietal Lobule
Precuneus
Superior Parietal Lobule
Middle Frontal Gyrus
Paracentral Lobule
Postcentral Gyrus
Precentral Gyrus
Superior Frontal Gyrus
Medial Frontal Gyrus
Uvula of Vermis
Pyramis of Vermis
Tuber of Vermis
Declive of Vermis
Culmen of Vermis
Cerebellar Tonsil
Inferior Semi-Lunar Lobule
Fastigium
Nodule
Uvula
Pyramis
Tuber
Declive
Culmen
Cerebellar Lingual
Hippocampus
Extra-Nuclear
Lentiform Nucleus
Amygdala
Hypothalamus
Red Nucleus
Substantia Nigra
Claustrum
Thalamus
Caudate
Cerebro-Spinal Fluid
Label 4
Gray Matter
White Matter
Label 5
Brodmann area 1
Brodmann area 2
Brodmann area 3
Brodmann area 4
Brodmann area 5
Brodmann area 6
Brodmann area 7
Brodmann area 8
Brodmann area 9
Brodmann area 10
Brodmann area 11
Brodmann area 12
Brodmann area 13
Brodmann area 17
Brodmann area 18
Brodmann area 19
Brodmann area 20
Brodmann area 21
Brodmann area 22
Brodmann area 23
Brodmann area 24
Brodmann area 25
Brodmann area 27
Brodmann area 28
Brodmann area 29
Brodmann area 30
Brodmann area 31
Brodmann area 32
Brodmann area 33
Brodmann area 34
Brodmann area 35
Brodmann area 36
Brodmann area 37
Brodmann area 38
Brodmann area 39
Brodmann area 40
Brodmann area 41
Brodmann area 42
Brodmann area 43
Brodmann area 44
Brodmann area 45
Brodmann area 46
Brodmann area 47
Caudate Tail
Caudate Body
Caudate Head
Dentate
Ventral Anterior Nucleus
Ventral Posterior Medial Nucleus
Ventral Posterior Lateral Nucleus
Medial Dorsal Nucleus
Lateral Dorsal Nucleus
Pulvinar
Lateral Posterior Nucleus
Ventral Lateral Nucleus
Midline Nucleus
Anterior Nucleus
Mammillary Body
Fourth Ventricle
Optic Tract
Anterior Commissure
Corpus Callosum
Third Ventricle
Medial Globus Pallidus
Lateral Globus Pallidus
Nucleus Accumbens Septi
Medial Geniculum Body
Lateral Geniculum Body
Subthalamic Nucleus
Lateral Ventricle
Putamen

-   ROIs from Talairach - Results

-  

-   Within the specified output directory, you'll find:

-  
    
-   
  • 
-   
    
-    The real stuff is in the .rois 
-    file, in the form of lists of indexes. To see how to make use of it, 
-    go here.
    
-   
  • 
-   
    
-    A verbose file .vrb,
-     with all the parameters being used.
    
-   
  • 
-   
    
-    Optionally, a volume .hdr / .img 
-    that will hold the equivalent regions in the form of a mask. A voxel 
-    in this volume holds a coded value which are listed in the associated .txt file.
    
-   

-  

-    

-  

-   Automatic creation of ROIs from the AAL or 
-   any Volume Mask

-  

-   This automatic generation needs a solution
-    points file plus a volume (MRI) 
-   which content is labels of regions, like the AAL.
-    It will then scan each labeled region from the mask and find the 
-   solution points that intersect it.

-  

-   Be sure that the solution points are coregistered to the mask 
-   (origin, orientation etc...) beforehand, otherwise the intersection 
-   will be empty!

-  

-    

-  

-   Called from the Tools
-    | Creating Rois menu, the following dialog appears:

-  

-   

-    

-   

-  

-   Note that only the relevant parameters to the current processing 
-   are being listed here:

-  

-   

-    
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-        
-      
-      
-        
-		
-      
-      
-        
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-    

-       

-        Input Files

-       

-         

-       

-        EEG / RIS / XYZ / SP file

-       

-        In our case, provide a solution
-         points file, for example with Drag & Drop.

-       

-        ROIs Volume Mask (optional):

-       

-        Actually, this is rather mandatory:  provide a MRI
-         file containing a mask for regions (like the AAL).

-       

-        ROIs Labels file (optional):

-       

-        Also provide a text file that 
-        associates the index of the volume mask with some textual/coded data.

-       

-        Cartool can provide for the AAL3v1 textual infos internally, see below.

-       

-        Processing Mode:

-       

-        Select Automatic

-       

-        Automatic Mode:

-       

-         

-       

-        SPs Intersecting a ROIS Volume:

-       

-        Select either  AAL3v1 ROIs  or  Other ROIs.
-        Both options work the same, just that in case of the AAL, you 
-        don't need the ROIs Labels file.

-			

-       

-        AAL3v1 ROIS

-       

-        You can select  AAL3v1 ROIs  if you are sure you 
-		dropped the AAL3v1 ROIs volume beforehand.

-	   

-        Don't use this option if you are unsure about which AAL version you are 
-		using, as the labelling and the volume might have some inconsistencies. 
-		In case of any doubt, just use the general purpose option below...

-       	 

-       

-        Other ROIS

-       

-        Select  Other ROIs  for any other ROIs that are not 
-		(currently) the AAL3v1. It will need the
-		dialog rois labels file specified 
-		to be able to work.

-       

-        See the syntax of the ROIs Labels file.

-       

-        Generating ROIs (optional text file):

-       

-        Give a file with the regions you would like to generate.

-       

-        If the field is empty, all possible ROIs will be generated.

-       

-        See below for the syntax of that file.

-       

-        Output

-       

-         

-       

-        Output Base File Name:

-       

-        Specifies a basis for all the file names that will be 
-        generated (main directory, common file name).

-       

-        Options:

-       

-         

-       

-        Open File(s) Upon Completion

-       

-        What it says...

-   

-  

-    

-  

-   ROIs from Volume Mask - Technical 
-   points & hints

-  

-   ROIs Labels file syntax

-  

-   This file associates the indexes from the volume mask to some textual
-    data. If this file is missing, Cartool can still use the indexes 
-   of the volume to generate ROIs.

-  

-    

-  

-   Here is the simple syntax of that file:

-  
    
-   
  • 
-   
    
-    one index + associated data per line
    
-   
  • 
-   
    
-    the volume index can be:
    
-   
      
-    
    • 
-    
      
-     the first integer value of the line
      
-    
    • 
-    
      
-     or, if not an integer, the current line number
      
-    
    
-   
  • 
-   
    
-    data following the index can be any number of textual parts 
-    separated by some space
    
-   

-  

-    

-  

-   See an example of a few lines:
1 Precentral_L 2001
2 Precentral_R 2002
3 Frontal_Sup_L 2101
4 Frontal_Sup_R 2102
...

-   Generating ROIs file syntax

-  

-   This file will tell which ROIs you want, and only them. Note 
-   that if this file is missing, all possible ROIs will be constructed!

-  

-    

-  

-   The syntax of the file is pretty lax, here are the rules:

-  
    
-   
  • 
-   
    
-    one ROI to generate per line, 
    
-   
  • 
-   
    
-    each line consists of one or multiple codes (specified 
-    in the MRI labels file). Each code 
-    could be:
    
-   
      
-    
    • 
-    
      
-     either the ROI index, like  123
      
-    
    • 
-    
      
-     any textual association from the ROIs Labels file, like  Precentral_L
      
-    
    • 
-    
      
-     in case of AAL, the value associated to each ROI, like  2001
      
-    
    
-   

-  

-    

-  

-   See an example to generate 7 ROIs:
Precentral_L  Precentral_R
3  4
2111  2112
ORG  ORD
Cuneus_L
Cuneus_R
91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108

-    

-  

-   Although you can mix all types of codes in the same file, and even on 
-   the same line, this is of course not regarded as a good practice! 
-   Stick to one notation, you are more likely to read this file than the computer!

-  

-    

-  

-   ROIs from Volume Mask - Results

-  

-   Within the specified output directory, you'll find:

-  
    
-   
  • 
-   
    
-    The real stuff is in the .rois 
-    file, in the form of lists of indexes. To see how to make use of it, 
-    go here.
    
-   
  • 
-   
    
-    A verbose file .vrb,
-     with all the parameters being used.
    
-   

-  

-   Interactive creation of ROIs

-  

-   This way of creating rois is achieved through user interaction,
-    by picking elements one at a time into a roi, one roi 
-   after the other.

-   This process could be done on the following files:

-  
-  

-    

-  

-   After creating the ROIs, see how to make use of them for Tracks
-    display, Potential display,
-    Inverse Solution display, Statistics 
-   or Export of EEG files.

-  

-   Interactive creation of ROIs from EEG or 
-   RIS tracks

-  

-   Call Tools
-    | Creating Rois to launch the following dialog (if you 
-   have already opened an EEG or a RIS file, the input field will 
-   be correctly pre-filled):

-  

-   

-    

-   

-  

-   Note that only the relevant parameters to the current processing 
-   are being listed here:

-  

-   

-    
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-    

-       

-        Input Files

-       

-         

-       

-        EEG / RIS / XYZ / SP file

-       

-        In our case, provide an EEG 
-        or a RIS 
-        file, for example with Drag & Drop.

-       

-        ROIs Volume file (optional):

-       

-        (not relevant here).

-       

-        ROIs Labels file (optional):

-       

-        (not relevant here).

-       

-        Processing Mode:

-       

-        Select Interactive

-       

-        Interactive Mode:

-       

-         

-       

-        Next ROI Name:

-       

-        Give a name for the current roi (spaces allowed).

-       

-        If you let this field empty... well, Cartool will name the roi 
-        itself, and it is known to have quite a bad taste at it (something as 
-        dull as "roi1", "roi2", "roi3"...). So 
-        it is not a good idea to not fill this field. In any case, when all 
-        is done and saved to a .rois 
-        file, you can still text-edit it and change the names...

-       

-        Next ROI Tracks:

-       

-        Add here all the names of the tracks you wish to be in the 
-        same roi.

-       

-        Now, the magic:

-       
    
-        
  • 
-        
    
-         switch back to the EEG window, and select the tracks you like (middle-click,
-          or whatever selection tools). All
-          your EEG selection will be shown in the "Tracks" field of 
-         the dialog!
    
-        
  • 
-        
    
-         Conversely, typing in the dialog field, or modifying the 
-         existing text in it will also be reflected in the EEG window! Wunderbar!
    
-        

-       

-        

-       

-        Add New Roi

-       

-        When all the tracks you want to be in one roi are shown in the 
-        previous field, clicking this will actually create the roi 
-        from the current input. So until you have clicked it, the roi is not 
-        recorded, and you can still modify it.

-       

-        Remove Last Roi

-       

-        What is says.

-       

-        Bonus track: the list of tracks of the removed roi is restored in the 
-        dialog, so you can re-edit it if you want.

-       

-        Output

-       

-         

-       

-        Output Base File Name:

-       

-        Specifies a basis for all the file names that will be 
-        generated (main directory, common file name).

-       

-        Options:

-       

-         

-       

-        Open File(s) Upon Completion

-       

-        What it says...

-   

-  

-    

-  

-   ROIs from EEG / RIS tracks - 
-   Technical points & hints

-  

-   Checking ROIs do not overlap

-  

-   Each time a roi is added, Cartool will check it does not overlap 
-   with any existing rois. If it finds some tracks that surreptuously 
-   sneaked in, they will be silently removed from the list of tracks 
-   before creating the roi.

-  

-   This makes the interactive creation fool-proof (not that we don't 
-   trust you, but...).

-  

-   Ending the interactive process

-  

-   Well, when you're done, just click the OK button to actually 
-   create the .rois 
-   file. If all tracks have been used into a roi, the Add New Roi 
-   button will disable itself in great disdain...

-  

-   Finally, Cartool will close the files it has opened.

-  

-   Using ROIs to reorder tracks display

-  

-   Within a given roi, the electrodes will also be reordered 
-   according to the exact sequence specified. Thought order does not 
-   matter for averaging purposes, it can be beneficial for displaying tracks 
-   according to a more intuitive scheme.

-  

-   F.ex. with high density nets of electrodes, the native ordering is 
-   basically non-intuitive:

-  

-   

-  

-   Then, with rois re-ordering (well this is just an example, not a 
-   winning price in design!):

-  

-   

-  

-   See also this topic.

-  

-   Final thoughts

-  

-   It is not really the best way to create rois from a RIS file, because 
-   there are too many track! Think more about automatic
-    creation in the case of inverse solution.

-  

-   In the case of EEG, it is quite sexy to work from an EEG linked 
-   with electrodes coordinates, so you can also see the selection on the 
-   electrodes of the potential display, too!

-  

-   ROIs from EEG / RIS tracks - Results

-  

-   Within the specified output directory, you'll find:

-  
    
-   
  • 
-   
    
-    The real stuff is in the .rois 
-    file, in the form of lists of indexes. To see how to make use of it, 
-    go here.
    
-   
  • 
-   
    
-    A verbose file .vrb,
-     with all the parameters being used.
    
-   

-  

-    

-  

-   Interactive creation of ROIs from 
-   electrodes or solution points

-  

-   Call Tools
-    | Creating Rois to launch the following dialog (if you 
-   have already opened an electrode or a solution points file, the input 
-   field will be correctly pre-filled):

-  

-   

-    

-   

-  

-   Note that only the relevant parameters to the current processing 
-   are being listed here:

-  

-   

-    
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-    

-       

-        Input Files

-       

-         

-       

-        EEG / RIS / XYZ / SP file

-       

-        In our case, provide an electrodes
-         coordinates file or a solution
-         points file, for example with Drag & Drop.

-       

-        ROIs Volume file (optional):

-       

-        (not relevant here).

-       

-        ROIs Labels file (optional):

-       

-        (not relevant here).

-       

-        Processing Mode:

-       

-        Select Interactive

-       

-        Interactive Mode:

-       

-         

-       

-        Next ROI Name:

-       

-        Give a name for the current roi (spaces allowed).

-       

-        If you let this field empty... well, Cartool will name the roi 
-        itself, and it is known to have quite a bad taste at it (something as 
-        dull as "roi1", "roi2", "roi3"...). So 
-        it is not a good idea to not fill this field. In any case, when all 
-        is done and saved to a .rois 
-        file, you can still text-edit it and change the names...

-       

-        Next ROI Tracks:

-       

-        Add here all the names of the tracks you wish to be in the 
-        same roi.

-       

-        Now, the magic:

-       
    
-        
  • 
-        
    
-         switch back to the electrode window, and select the tracks you 
-         like (with middle-click).
-          All selected electrodes will be shown in the "Tracks" 
-         field of the dialog!
    
-        
  • 
-        
    
-         Conversely, typing in the dialog field, or modifying the 
-         existing text in it will also be reflected in the electrode window!
-          Wunderschön!
    
-        

-       

-        

-       

-        Add New Roi

-       

-        When all the electrodes you want to be in one roi are shown in the 
-        previous field, clicking this will actually create the roi 
-        from the current input. So until you have clicked it, the roi is not 
-        recorded, and you can still modify it.

-       

-        Remove Last Roi

-       

-        What is says.

-       

-        Bonus track: the list of electrodes of the removed roi is restored in 
-        the dialog, so you can re-edit it if you want.

-       

-        Output

-       

-         

-       

-        Output Base File Name:

-       

-        Specifies a basis for all the file names that will be 
-        generated (main directory, common file name).

-       

-        Options:

-       

-         

-       

-        Open File(s) Upon Completion

-       

-        What it says...

-   

-  

-    

-  

-   ROIs from electrodes or solution 
-   points - Technical points & hints

-  

-   Most of these points are also 
-   relevant here!

-  

-   And for the solution points?

-  

-   Well, you can technically use this manual method:

-  
    
-   
  • 
-   
    
-    if you have only a few rois / solution points to look after,
    
-   
  • 
-   
    
-    make use of the slice display to show less points at a time,
    
-   
  • 
-   
    
-    and be patient.
    
-   

-  

-   Otherwise, think about the automatic processes!

-  

-   ROIs from electrodes or solution points 
-   - Results

-  

-   Within the specified output directory, you'll find:

-  
    
-   
  • 
-   
    
-    The real stuff is in the .rois 
-    file, in the form of lists of indexes. To see how to make use of it, 
-    go here.
    
-   
  • 
-   
    
-    A verbose file .vrb,
-     with all the parameters being used.
    
-   

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    
+ 
+     

+         

+             Creating ROIs
+         

+         

+              
+         

+         

+             This page is about creating the .rois files,
+             the preliminary step before actually being able to apply the 
+                 
+                     rois
+                     calculus
+                 
+              itself. The .rois files are actually
+             just groups of indexes (of tracks, electrodes, solution points, or whatever).
+         

+         

+             Creating rois can be done either automatically or through 
+                 user
+                 interaction
+             .
+         

+         

+              
+         

+         

+             Automatic creation of ROIs
+         

+         
+         

+             Interactive creation of ROIs
+         

+         
+         

+             Automatic creation of ROIs
+         

+         

+             This way of generating .rois files
+             is done by looking for the 
+                 intersection of the solution points
+                 with a volume mask
+             . The generated ROIs can then be used either
+             with the Inverse Solution display,
+             the Statistics or the Export
+             of RIS files.
+         

+         

+             Three options are available:
+         

+         
    
+             
  • 
+                 
    
+                     specifying a set of Talairach regions,
+                 
    
+             
  • 
+                 
    
+                     scanning the AAL
+                         volume mask
+                     ,
+                 
    
+             
  • 
+                 
    
+                     scanning any arbitrary volume mask that contains some region labels.
+                 
    
+         

+         

+              
+         

+         

+             Automatic creation of ROIs from
+             Talairach regions
+         

+         

+             This automatic generation needs a 
+                 
+                     solution
+                     points file
+                 
+              that has a 
+                 Talairach
+                 transformation function attached to it
+             . If this
+             function is available, you can simply provide a 
+                 text file naming
+                 some Talaraich regions
+             , and Cartool will create the groups of
+             solution points that fit within each of the named regions.
+         

+         

+              
+         

+         

+             Called from the 
+                 
+                     Tools
+                     | Creating Rois
+                 
+              menu, the following dialog appears:
+         

+         

+             

+                 
+             

+         

+         

+             
+                 Note that only the relevant parameters to the current processing
+                 are being listed here:
+             
+         

+         

+             

+                 
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                 

+                             

+                                 Input Files
+                         

+                             

+                                  
+                         

+                             

+                                 EEG / RIS / XYZ / SP file
+                         

+                             

+                                 In our case, provide a 
+                                     
+                                         solution
+                                         points file
+                                     
+                                 , with 
+                                     Talaraich
+                                     abilities
+                                 .
+                             

+                             

+                                 Use Drag & Drop to save time!
+                         

+                             

+                                 ROIs Volume file (optional):
+                         

+                             

+                                 You can optionally provide a MRI file
+                                 containing a grey matter / brain mask.
+                             

+                             

+                                 This MRI will solely be used for generating another mask MRI, with
+                                 the labels generated from the specified Talairach regions.
+                         

+                             

+                                 ROIs Labels file (optional):
+                         

+                             

+                                 (not relevant here, Talairach names are hard-encoded in Cartool).
+                         

+                             

+                                 Processing Mode:
+                         

+                             

+                                 Select Automatic
+                         

+                             

+                                 Automatic Mode:
+                         

+                             

+                                  
+                         

+                             

+                                 SPs Intersecting a ROIS Volume:
+                         

+                             

+                                 Select Talairach ROIs
+                         

+                             

+                                 Generating ROIs (optional text file):
+                         

+                             

+                                 Give a file with the Talairach regions you would like to generate.
+                             

+                             

+                                 This file is actually mandatory for the Talairach case...
+                             

+                             

+                                 See below for the (simplistic) syntax
+                                 of the file.
+                         

+                             

+                                 Output
+                         

+                             

+                                  
+                         

+                             

+                                 Output Base File Name:
+                         

+                             

+                                 Specifies a basis for all the file names that will be
+                                 generated (main directory, common file name).
+                         

+                             

+                                 Options:
+                         

+                             

+                                  
+                         

+                             

+                                 Open File(s) Upon Completion
+                         

+                             

+                                 What it says...
+                         

+             

+         

+         

+              
+         

+         

+             ROIs from Talairach - Technical points
+             & hints
+         

+         

+             Naming convention
+         

+         

+             The text file containing the named Talairach regions follow a very
+             simple syntax:
+         

+         
    
+             
  • 
+                 
    
+                     each line is a region,
+                 
    
+             
  • 
+                 
    
+                     optionally, the line can begin with either the Right or Left keyword,
+                 
    
+             
  • 
+                 
    
+                     use one or more of the known Talairach labels
+                     listed below, separated by a comma "," . If more
+                     than one label is listed, this means the intersection of the
+                     regions will be used.
+                 
    
+         

+         

+              
+         

+         

+             As usual (!) Cartool tries to ease your work, so when specifying the Right
+             or Left keywords, what it does is gathering (adding together)
+             all the labels which holds this keyword, silently compounding a whole
+             left or right structure. Then only it will be intersected with the
+             named Talairach region that follows. It is even possible to just
+             specify Left or Right on a line, just to see all the structures on
+             the left and right (respectively).
+         

+         

+              
+         

+         

+             Example of valid namings:
+         
Left Cerebrum
Right Cerebrum
Left Posterior Lobe
Right Posterior Lobe
Left Occipital Lobe, Middle Occipital Gyrus
Left Occipital Lobe, Middle Occipital Gyrus, Gray Matter

+             Recognized Talairach names
+         

+         

+             Here are all the labels Cartool will recognize:
+         
Label 1
Inter-Hemispheric
Left Cerebrum
Right Cerebrum
Right Cerebellum
Right Brainstem
Left Brainstem
Left Cerebellum
Label 2
Posterior Lobe
Anterior Lobe
Frontal-Temporal Space
Limbic Lobe
Medulla
Pons
Midbrain
Sub-lobar
Occipital Lobe
Temporal Lobe
Parietal Lobe
Frontal Lobe
Label 3
Posterior Cingulate
Anterior Cingulate
Subcallosal Gyrus
Sub-Gyral
Transverse Temporal Gyrus
Uncus
Rectal Gyrus
Fusiform Gyrus
Inferior Occipital Gyrus
Inferior Temporal Gyrus
Insula
Parahippocampal Gyrus
Lingual Gyrus
Middle Occipital Gyrus
Orbital Gyrus
Middle Temporal Gyrus
Superior Temporal Gyrus
Superior Occipital Gyrus
Precentral Gyrus
Inferior Frontal Gyrus
Cuneus
Angular Gyrus
Supramarginal Gyrus
Cingulate Gyrus
Inferior Parietal Lobule
Precuneus
Superior Parietal Lobule
Middle Frontal Gyrus
Paracentral Lobule
Postcentral Gyrus
Precentral Gyrus
Superior Frontal Gyrus
Medial Frontal Gyrus
Uvula of Vermis
Pyramis of Vermis
Tuber of Vermis
Declive of Vermis
Culmen of Vermis
Cerebellar Tonsil
Inferior Semi-Lunar Lobule
Fastigium
Nodule
Uvula
Pyramis
Tuber
Declive
Culmen
Cerebellar Lingual
Hippocampus
Extra-Nuclear
Lentiform Nucleus
Amygdala
Hypothalamus
Red Nucleus
Substantia Nigra
Claustrum
Thalamus
Caudate
Cerebro-Spinal Fluid
Label 4
Gray Matter
White Matter
Label 5
Brodmann area 1
Brodmann area 2
Brodmann area 3
Brodmann area 4
Brodmann area 5
Brodmann area 6
Brodmann area 7
Brodmann area 8
Brodmann area 9
Brodmann area 10
Brodmann area 11
Brodmann area 12
Brodmann area 13
Brodmann area 17
Brodmann area 18
Brodmann area 19
Brodmann area 20
Brodmann area 21
Brodmann area 22
Brodmann area 23
Brodmann area 24
Brodmann area 25
Brodmann area 27
Brodmann area 28
Brodmann area 29
Brodmann area 30
Brodmann area 31
Brodmann area 32
Brodmann area 33
Brodmann area 34
Brodmann area 35
Brodmann area 36
Brodmann area 37
Brodmann area 38
Brodmann area 39
Brodmann area 40
Brodmann area 41
Brodmann area 42
Brodmann area 43
Brodmann area 44
Brodmann area 45
Brodmann area 46
Brodmann area 47
Caudate Tail
Caudate Body
Caudate Head
Dentate
Ventral Anterior Nucleus
Ventral Posterior Medial Nucleus
Ventral Posterior Lateral Nucleus
Medial Dorsal Nucleus
Lateral Dorsal Nucleus
Pulvinar
Lateral Posterior Nucleus
Ventral Lateral Nucleus
Midline Nucleus
Anterior Nucleus
Mammillary Body
Fourth Ventricle
Optic Tract
Anterior Commissure
Corpus Callosum
Third Ventricle
Medial Globus Pallidus
Lateral Globus Pallidus
Nucleus Accumbens Septi
Medial Geniculum Body
Lateral Geniculum Body
Subthalamic Nucleus
Lateral Ventricle
Putamen

+             ROIs from Talairach - Results
+         

+         

+             Within the specified output directory, you'll find:
+         

+         
    
+             
  • 
+                 
    
+                     The real stuff is in the .rois
+                     file, in the form of lists of indexes. To see how to make use of it,
+                     go here.
+                 
    
+             
  • 
+                 
    
+                     A verbose file .vrb,
+                     with all the parameters being used.
+                 
    
+             
  • 
+                 
    
+                     Optionally, a volume .hdr / .img
+                     that will hold the equivalent regions in the form of a mask. A voxel
+                     in this volume holds a coded value which are listed in the associated .txt file.
+                 
    
+         

+         

+              
+         

+         

+             Automatic creation of ROIs from the AAL or
+             any Volume Mask
+         

+         

+             This automatic generation needs a 
+                 
+                     solution
+                     points file
+                 
+              plus a volume (MRI)
+             which content is labels of regions, like the AAL.
+             It will then scan each labeled region from the mask and find the
+             solution points that intersect it.
+         

+         

+             Be sure that the solution points are coregistered to the mask
+             (origin, orientation etc...) beforehand, otherwise the intersection
+             will be empty!
+         

+         

+              
+         

+         

+             Called from the 
+                 
+                     Tools
+                     | Creating Rois
+                 
+              menu, the following dialog appears:
+         

+         

+             

+                 
+             

+         

+         

+             
+                 Note that only the relevant parameters to the current processing
+                 are being listed here:
+             
+         

+         

+             

+                 
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                 

+                             

+                                 Input Files
+                         

+                             

+                                  
+                         

+                             

+                                 EEG / RIS / XYZ / SP file
+                         

+                             

+                                 In our case, provide a 
+                                     
+                                         solution
+                                         points file
+                                     
+                                 , for example with Drag & Drop.
+                         

+                             

+                                 ROIs Volume Mask (optional):
+                         

+                             

+                                 Actually, this is rather mandatory:  provide a 
+                                     
+                                         MRI
+                                         file
+                                     
+                                  containing a mask for regions (like the AAL).
+                         

+                             

+                                 ROIs Labels file (optional):
+                         

+                             

+                                 Also provide a text file that
+                                 associates the index of the volume mask with some textual/coded data.
+                             

+                             

+                                 Cartool can provide for the AAL3v1 textual infos internally, see below.
+                         

+                             

+                                 Processing Mode:
+                         

+                             

+                                 Select Automatic
+                         

+                             

+                                 Automatic Mode:
+                         

+                             

+                                  
+                         

+                             

+                                 SPs Intersecting a ROIS Volume:
+                         

+                             

+                                 Select either  AAL3v1 ROIs  or  Other ROIs.
+                                 Both options work the same, just that in case of the AAL, you
+                                 don't need the ROIs Labels file.
+                             

+                         

+                             

+                                 AAL3v1 ROIS
+                         

+                             

+                                 You can select  AAL3v1 ROIs  if you are sure you
+                                 dropped the AAL3v1 ROIs volume beforehand.
+                             

+                             

+                                 Don't use this option if you are unsure about which AAL version you are
+                                 using, as the labelling and the volume might have some inconsistencies.
+                                 In case of any doubt, just use the general purpose option below...
+                             

+                         

+                             

+                                 Other ROIS
+                         

+                             

+                                 Select  Other ROIs  for any other ROIs that are not
+                                 (currently) the AAL3v1. It will need the
+                                 dialog rois labels file specified
+                                 to be able to work.
+                             

+                             

+                                 See the syntax of the ROIs Labels file.
+                         

+                             

+                                 Generating ROIs (optional text file):
+                         

+                             

+                                 Give a file with the regions you would like to generate.
+                             

+                             

+                                 If the field is empty, all possible ROIs will be generated.
+                             

+                             

+                                 See below for the syntax of that file.
+                         

+                             

+                                 Output
+                         

+                             

+                                  
+                         

+                             

+                                 Output Base File Name:
+                         

+                             

+                                 Specifies a basis for all the file names that will be
+                                 generated (main directory, common file name).
+                         

+                             

+                                 Options:
+                         

+                             

+                                  
+                         

+                             

+                                 Open File(s) Upon Completion
+                         

+                             

+                                 What it says...
+                         

+             

+         

+         

+              
+         

+         

+             ROIs from Volume Mask - Technical
+             points & hints
+         

+         

+             ROIs Labels file syntax
+         

+         

+             This file associates the indexes from the volume mask to some 
+                 textual
+                 data
+             . If this file is missing, Cartool can still use the indexes
+             of the volume to generate ROIs.
+         

+         

+              
+         

+         

+             Here is the simple syntax of that file:
+         

+         
    
+             
  • 
+                 
    
+                     one index + associated data per line
+                 
    
+             
  • 
+                 
    
+                     the volume index can be:
+                 
    
+                 
      
+                     
    • 
+                         
      
+                             the first integer value of the line
+                         
      
+                     
    • 
+                         
      
+                             or, if not an integer, the current line number
+                         
      
+                 
    
+             
  • 
+                 
    
+                     data following the index can be any number of textual parts
+                     separated by some space
+                 
    
+         

+         

+              
+         

+         

+             See an example of a few lines:
+         
1 Precentral_L 2001
2 Precentral_R 2002
3 Frontal_Sup_L 2101
4 Frontal_Sup_R 2102
...

+             Generating ROIs file syntax
+         

+         

+             This file will tell which ROIs you want, and only them. Note
+             that if this file is missing, all possible ROIs will be constructed!
+         

+         

+              
+         

+         

+             The syntax of the file is pretty lax, here are the rules:
+         

+         
    
+             
  • 
+                 
    
+                     one ROI to generate per line,
+                 
    
+             
  • 
+                 
    
+                     each line consists of one or multiple codes (specified
+                     in the MRI labels file). Each code
+                     could be:
+                 
    
+                 
      
+                     
    • 
+                         
      
+                             either the ROI index, like  123
+                         
      
+                     
    • 
+                         
      
+                             any textual association from the ROIs Labels file, like  Precentral_L
+                         
      
+                     
    • 
+                         
      
+                             in case of AAL, the value associated to each ROI, like  2001
+                         
      
+                 
    
+         

+         

+              
+         

+         

+             See an example to generate 7 ROIs:
+         
Precentral_L  Precentral_R
3  4
2111  2112
ORG  ORD
Cuneus_L
Cuneus_R
91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108

+              
+         

+         

+             Although you can mix all types of codes in the same file, and even on
+             the same line, this is of course not regarded as a good practice!
+             Stick to one notation, you are more likely to read this file than the computer!
+         

+         

+              
+         

+         

+             ROIs from Volume Mask - Results
+         

+         

+             Within the specified output directory, you'll find:
+         

+         
    
+             
  • 
+                 
    
+                     The real stuff is in the .rois
+                     file, in the form of lists of indexes. To see how to make use of it,
+                     go here.
+                 
    
+             
  • 
+                 
    
+                     A verbose file .vrb,
+                     with all the parameters being used.
+                 
    
+         

+         

+             Interactive creation of ROIs
+         

+         

+             This way of creating rois is achieved through user interaction,
+             by picking elements one at a time into a roi, 
+                 one roi
+                 after the other
+             .

+             This process could be done on the following files:
+         

+         
+         

+              
+         

+         

+             After creating the ROIs, see how to make use of them for 
+                 Tracks
+                 display
+             , Potential display,
+             Inverse Solution display, Statistics
+             or Export of EEG files.
+         

+         

+             Interactive creation of ROIs from EEG or
+             RIS tracks
+         

+         

+             Call 
+                 
+                     Tools
+                     | Creating Rois
+                 
+              to launch the following dialog (if you
+             have already opened an EEG or a RIS file, the input field will
+             be correctly pre-filled):
+         

+         

+             

+                 
+             

+         

+         

+             
+                 Note that only the relevant parameters to the current processing
+                 are being listed here:
+             
+         

+         

+             

+                 
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                 

+                             

+                                 Input Files
+                         

+                             

+                                  
+                         

+                             

+                                 EEG / RIS / XYZ / SP file
+                         

+                             

+                                 In our case, provide an EEG
+                                 or a RIS
+                                 file, for example with Drag & Drop.
+                         

+                             

+                                 ROIs Volume file (optional):
+                         

+                             

+                                 (not relevant here).
+                         

+                             

+                                 ROIs Labels file (optional):
+                         

+                             

+                                 (not relevant here).
+                         

+                             

+                                 Processing Mode:
+                         

+                             

+                                 Select Interactive
+                         

+                             

+                                 Interactive Mode:
+                         

+                             

+                                  
+                         

+                             

+                                 Next ROI Name:
+                         

+                             

+                                 Give a name for the current roi (spaces allowed).
+                             

+                             

+                                 If you let this field empty... well, Cartool will name the roi
+                                 itself, and it is known to have quite a bad taste at it (something as
+                                 dull as "roi1", "roi2", "roi3"...). So
+                                 it is not a good idea to not fill this field. In any case, when all
+                                 is done and saved to a .rois
+                                 file, you can still text-edit it and change the names...
+                         

+                             

+                                 Next ROI Tracks:
+                         

+                             

+                                 Add here all the names of the tracks you wish to be in the
+                                 same roi.
+                             

+                             

+                                 Now, the magic:
+                             

+                             
    
+                                 
  • 
+                                     
    
+                                         switch back to the EEG window, and select the tracks you like (middle-click,
+                                         or whatever selection tools). 
+                                             All
+                                             your EEG selection will be shown in the "Tracks" field of
+                                             the dialog!
+                                         
+                                     
    
+                                 
  • 
+                                     
    
+                                         Conversely, typing in the dialog field, or modifying the
+                                         existing text in it will also be reflected in the EEG window! Wunderbar!
+                                     
    
+                             

+                             

+                                 
+                         

+                             

+                                 Add New Roi
+                         

+                             

+                                 When all the tracks you want to be in one roi are shown in the
+                                 previous field, clicking this will actually create the roi
+                                 from the current input. So until you have clicked it, the roi is not
+                                 recorded, and you can still modify it.
+                         

+                             

+                                 Remove Last Roi
+                         

+                             

+                                 What is says.
+                             

+                             

+                                 Bonus track: the list of tracks of the removed roi is restored in the
+                                 dialog, so you can re-edit it if you want.
+                         

+                             

+                                 Output
+                         

+                             

+                                  
+                         

+                             

+                                 Output Base File Name:
+                         

+                             

+                                 Specifies a basis for all the file names that will be
+                                 generated (main directory, common file name).
+                         

+                             

+                                 Options:
+                         

+                             

+                                  
+                         

+                             

+                                 Open File(s) Upon Completion
+                         

+                             

+                                 What it says...
+                         

+             

+         

+         

+              
+         

+         

+             ROIs from EEG / RIS tracks -
+             Technical points & hints
+         

+         

+             Checking ROIs do not overlap
+         

+         

+             Each time a roi is added, Cartool will check it does not overlap
+             with any existing rois. If it finds some tracks that surreptuously
+             sneaked in, they will be silently removed from the list of tracks
+             before creating the roi.
+         

+         

+             This makes the interactive creation fool-proof (not that we don't
+             trust you, but...).
+         

+         

+             Ending the interactive process
+         

+         

+             Well, when you're done, just click the OK button to actually
+             create the .rois
+             file. If all tracks have been used into a roi, the Add New Roi
+             button will disable itself in great disdain...
+         

+         

+             Finally, Cartool will close the files it has opened.
+         

+         

+             Using ROIs to reorder tracks display
+         

+         

+             Within a given roi, the electrodes will also be reordered
+             according to the exact sequence specified. Thought order does not
+             matter for averaging purposes, it can be beneficial for displaying tracks
+             according to a more intuitive scheme.
+         

+         

+             F.ex. with high density nets of electrodes, the native ordering is
+             basically non-intuitive:
+         

+         

+             
+         

+         

+             Then, with rois re-ordering (well this is just an example, not a
+             winning price in design!):
+         

+         

+             
+         

+         

+             See also this topic.
+         

+         

+             Final thoughts
+         

+         

+             It is not really the best way to create rois from a RIS file, because
+             there are too many track! Think more about 
+                 automatic
+                 creation
+              in the case of inverse solution.
+         

+         

+             In the case of EEG, it is quite sexy to work from an EEG linked
+             with electrodes coordinates, so you can also see the selection on the
+             electrodes of the potential display, too!
+         

+         

+             ROIs from EEG / RIS tracks - Results
+         

+         

+             Within the specified output directory, you'll find:
+         

+         
    
+             
  • 
+                 
    
+                     The real stuff is in the .rois
+                     file, in the form of lists of indexes. To see how to make use of it,
+                     go here.
+                 
    
+             
  • 
+                 
    
+                     A verbose file .vrb,
+                     with all the parameters being used.
+                 
    
+         

+         

+              
+         

+         

+             Interactive creation of ROIs from
+             electrodes or solution points
+         

+         

+             Call 
+                 
+                     Tools
+                     | Creating Rois
+                 
+              to launch the following dialog (if you
+             have already opened an electrode or a solution points file, the input
+             field will be correctly pre-filled):
+         

+         

+             

+                 
+             

+         

+         

+             
+                 Note that only the relevant parameters to the current processing
+                 are being listed here:
+             
+         

+         

+             

+                 
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                 

+                             

+                                 Input Files
+                         

+                             

+                                  
+                         

+                             

+                                 EEG / RIS / XYZ / SP file
+                         

+                             

+                                 In our case, provide an 
+                                     
+                                         electrodes
+                                         coordinates file
+                                     
+                                  or a 
+                                     
+                                         solution
+                                         points file
+                                     
+                                 , for example with Drag & Drop.
+                         

+                             

+                                 ROIs Volume file (optional):
+                         

+                             

+                                 (not relevant here).
+                         

+                             

+                                 ROIs Labels file (optional):
+                         

+                             

+                                 (not relevant here).
+                         

+                             

+                                 Processing Mode:
+                         

+                             

+                                 Select Interactive
+                         

+                             

+                                 Interactive Mode:
+                         

+                             

+                                  
+                         

+                             

+                                 Next ROI Name:
+                         

+                             

+                                 Give a name for the current roi (spaces allowed).
+                             

+                             

+                                 If you let this field empty... well, Cartool will name the roi
+                                 itself, and it is known to have quite a bad taste at it (something as
+                                 dull as "roi1", "roi2", "roi3"...). So
+                                 it is not a good idea to not fill this field. In any case, when all
+                                 is done and saved to a .rois
+                                 file, you can still text-edit it and change the names...
+                         

+                             

+                                 Next ROI Tracks:
+                         

+                             

+                                 Add here all the names of the tracks you wish to be in the
+                                 same roi.
+                             

+                             

+                                 Now, the magic:
+                             

+                             
    
+                                 
  • 
+                                     
    
+                                         switch back to the electrode window, and select the tracks you
+                                         like (with middle-click).
+                                         
+                                             All selected electrodes will be shown in the "Tracks"
+                                             field of the dialog!
+                                         
+                                     
    
+                                 
  • 
+                                     
    
+                                         Conversely, typing in the dialog field, or modifying the
+                                         existing text in it will also be reflected in the electrode window!
+                                         Wunderschön!
+                                     
    
+                             

+                             

+                                 
+                         

+                             

+                                 Add New Roi
+                         

+                             

+                                 When all the electrodes you want to be in one roi are shown in the
+                                 previous field, clicking this will actually create the roi
+                                 from the current input. So until you have clicked it, the roi is not
+                                 recorded, and you can still modify it.
+                         

+                             

+                                 Remove Last Roi
+                         

+                             

+                                 What is says.
+                             

+                             

+                                 Bonus track: the list of electrodes of the removed roi is restored in
+                                 the dialog, so you can re-edit it if you want.
+                         

+                             

+                                 Output
+                         

+                             

+                                  
+                         

+                             

+                                 Output Base File Name:
+                         

+                             

+                                 Specifies a basis for all the file names that will be
+                                 generated (main directory, common file name).
+                         

+                             

+                                 Options:
+                         

+                             

+                                  
+                         

+                             

+                                 Open File(s) Upon Completion
+                         

+                             

+                                 What it says...
+                         

+             

+         

+         

+              
+         

+         

+             ROIs from electrodes or solution
+             points - Technical points & hints
+         

+         

+             Most of these points are also
+             relevant here!
+         

+         

+             And for the solution points?
+         

+         

+             Well, you can technically use this manual method:
+         

+         
    
+             
  • 
+                 
    
+                     if you have only a few rois / solution points to look after,
+                 
    
+             
  • 
+                 
    
+                     make use of the slice display to show less points at a time,
+                 
    
+             
  • 
+                 
    
+                     and be patient.
+                 
    
+         

+         

+             Otherwise, think about the automatic processes!
+         

+         

+             ROIs from electrodes or solution points
+             - Results
+         

+         

+             Within the specified output directory, you'll find:
+         

+         
    
+             
  • 
+                 
    
+                     The real stuff is in the .rois
+                     file, in the form of lists of indexes. To see how to make use of it,
+                     go here.
+                 
    
+             
  • 
+                 
    
+                     A verbose file .vrb,
+                     with all the parameters being used.
+                 
    
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+     

  
 
\ No newline at end of file
diff --git a/docs/ReferenceGuide/creating-template-electrodes.html b/docs/ReferenceGuide/creating-template-electrodes.html
index 934064f4..e09f078c 100644
--- a/docs/ReferenceGuide/creating-template-electrodes.html
+++ b/docs/ReferenceGuide/creating-template-electrodes.html
@@ -2,288 +2,394 @@
  
   Creating a Template Electrodes Coordinates
  
- 
-  

-   Creating a Template Electrodes Coordinates

-  

-    

-  

-   What is averaging electrodes

-   How to run the averaging
Results

-  

-   What is averaging electrodes?

-  

-   This is a utility to build an average electrodes coordinates file 
-   from a set of subjects or measurements (average is the left one):

-  
    
-   
    
-    
    
-   

-  

-   Method

-  

-   The method works this way, with the 2 first stages being the main ones:

-  
    
-   
  • 
-   
    
-    Building a first temporary average, by coregistering all files 
-    to the first one.
    
-   
    
-    Coregistration is done by minimizing the sum of the squared distances 
-    between the same electrodes, with a global optimization process. The 
-    transformation function has 7 parameters (3 for translations, 3 for 
-    rotations, 1 for global scaling).
    
-   
  • 
-   
    
-    Coregistering all files to the current average, then averaging
-     the results to have a new average.
    
-   
    
-    This is repeated a few times (convergence is quite fast), and the 
-    same 7 parameters function is used.
    
-   
  • 
-   
    
-    Finally, some post-processing:
    
-   
      
-    
    • 
-    
      
-     Symmetrizing the final average;
      
-    
    • 
-    
      
-     Re-orienting to the RAS system (X: Right, Y: Anterior, Z: Superior);
      
-    
    • 
-    
      
-     Aligning the Y axis to the line Fpz-Oz.
      
-    
    
-   
  • 
-   
    
-    Computing the final quality measures.
    
-   

-  

-   Remarks

-  

-   The method is insensitive to which file is picked first in the first 
-   stage, apart for a slight different global scaling.

-  

-   The number of repetitions of the second stage is currently set to 3, 
-   as the resulting average does not evolve significantly afterward.

-  

-   Only a global scaling is allowed, and not 3 different scalings for 
-   each axis. We want to average the shape of the heads, and 
-   having different factors in x, y or z does alter the original 
-   shape. Plus, it would make the whole process very dependent to which 
-   file is picked in the first stage.

-  

-   How to run the averaging

-  

-   Called from the Tools
-    | Averaging Electrodes Coordinates menu, you simply have 
-   to follow these steps (no dialog for the moment):

-  
    
-   
  • 
-   
    
-    Give the list of files to be averaged;
    
-   
  • 
-   
    
-    Give the output file name;
    
-   
  • 
-   
    
-    Provide the Cz, Fpz and Oz approximate locations
    
-   
    
-    (you can specify up to 4 electrodes for each locus, like "125 
-    138 137", to use their average position).
    
-   
  • 
-   
    
-    The process begins straight away. At the end, it can burps a few 
-    error messages that are worth reading, usually indicating that the 
-    result is somehow unreliable and some files to be excluded.
    
-   

-  

-   Input files

-  

-   The files to be averaged should be taken from the same 
-   source/process of measurement:

-  
    
-   
  • 
-   
    
-    They should have the same orientation (though it can be arbitrary),
    
-   
  • 
-   
    
-    the same number of electrodes (!),
    
-   
  • 
-   
    
-    but centers, scalings and some rotations are allowed (and expected), 
-    and can be arbitrary.
    
-   

-  

-   Cz / Fpz / Oz locations

-  

-   See here an example for specifying Fpz, as we gave the electrodes 25 
-   26 and 32, so to have Fpz in the middle of these 3 points:

-  
    
-   
    
-    
    
-   

-  

-   Results

-  

-   Here are the output files:

-  
    
-   
  • 
-   
    
-    All files will begin with the output file given;
    
-   
  • 
-   
    
-    A .xyz file for the 
-    average electrodes;
    
-   
  • 
-   
    
-    A .Distances.sef 
-    file for the distances to the final average
    
-   
  • 
-   
    
-    A .vrb verbose file.
    
-   

-  

-    

-  

-   To help visualize, see here 3 coregistered files (blue meshes & 
-   electrodes) on top of the final average (yellow triangles):

-  
    
-   
    
-    
    
-   

-  

-    

-  

-   Distance file

-  

-   It indicates the distance of each file to the average, for each 
-   electrode (distance from the blue electrodes to the yellow ones in 
-   the figure above). The Y axis are the electrodes, and the X axis is 
-   the index of each of the original files.

-  

-   Plus, there are 2 more positions in X ("files"):

-  
    
-   
  • 
-   
    
-    The average of the distances, per electrode, across all files.
    
-   
    
-    This measure is equivalent to a Mean Absolute Deviation, and 
-    measures the distance from the data set to the average.
    
-   
  • 
-   
    
-    The dispersion of the distances, per electrode, across all files.
    
-   
    
-    This measure is a within group average distance (average of distances 
-    of all pairs of data), and measures the variability of the 
-    coregistered data.
    
-   
    
-    Note that the SD of the distance to the average is not a very 
-    interesting measure here: if all files are all wrong but within an 
-    equal range, the SD would be low anyway, even though the coregistered 
-    data being far.
    
-   

-  

-    

-  

-   You can of course link this distance 
-   file with the average .xyz to visualize the results, 
-   here we can see the average of electrodes distances:

-  
    
-   
    
-    
    
-   

-  

-   Verbose file

-  

-   It contains all the input parameters, the content of the distance 
-   file plus some more details.

-  

-   In addition to the distance, you will find 2 more rows (in Y):

-  
    
-   
  • 
-   
    
-    The average of the distances, per file, across all electrodes,
    
-   
    
-    including on the last 2 columns the average of average of distances, 
-    and the average of dispersion.
    
-   
  • 
-   
    
-    The Coefficient of Variation of the distances (CoV, normalized 
-    SD/Avg), per file, across all electrodes,
    
-   
    
-    including on the last 2 columns the CoV of the average (not 
-    the average of the CoV) and the CoV of dispersion.
    
-   

-  

-    

-  

-   Error messages

-  

-   The error messages you might have had at the end of the processing 
-   are also reproduced into the verbose file, so you can have a second 
-   thought on them:

-  
    
-   
  • 
-   
    
-    It could be that a file is considered globally unfit to the average,
-     by comparing the average distance across all the electrodes, to the 
-    average of average of distances.
    
-   
  • 
-   
    
-    Or it could be that some electrodes of a file are considered 
-    locally unfit to the average, by comparing its CoV of all 
-    electrodes to about 52%.
    
-   

-  

-   The advice is to first remove the files of the first category, run 
-   again the averaging, then only remove the files of the second 
-   category, if there remain some anymore.

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    
+ 
+     

+         

+             Creating a Template Electrodes Coordinates
+         

+         

+              
+         

+         

+             What is averaging electrodes

+             How to run the averaging
Results
+         

+         

+             What is averaging electrodes?
+         

+         

+             This is a utility to build an average electrodes coordinates file
+             from a set of subjects or measurements (average is the left one):
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+             Method
+         

+         

+             The method works this way, with the 2 first stages being the main ones:
+         

+         
    
+             
  • 
+                 
    
+                     Building a first temporary average, by coregistering all files
+                     to the first one.
+                 
    
+                 
    
+                     Coregistration is done by minimizing the sum of the squared distances
+                     between the same electrodes, with a global optimization process. The
+                     transformation function has 7 parameters (3 for translations, 3 for
+                     rotations, 1 for global scaling).
+                 
    
+             
  • 
+                 
    
+                     Coregistering all files to the current average, then 
+                         averaging
+                         the results to have a new average
+                     .
+                 
    
+                 
    
+                     This is repeated a few times (convergence is quite fast), and the
+                     same 7 parameters function is used.
+                 
    
+             
  • 
+                 
    
+                     Finally, some post-processing:
+                 
    
+                 
      
+                     
    • 
+                         
      
+                             Symmetrizing the final average;
+                         
      
+                     
    • 
+                         
      
+                             Re-orienting to the RAS system (X: Right, Y: Anterior, Z: Superior);
+                         
      
+                     
    • 
+                         
      
+                             Aligning the Y axis to the line Fpz-Oz.
+                         
      
+                 
    
+             
  • 
+                 
    
+                     Computing the final quality measures.
+                 
    
+         

+         

+             Remarks
+         

+         

+             The method is insensitive to which file is picked first in the first
+             stage, apart for a slight different global scaling.
+         

+         

+             The number of repetitions of the second stage is currently set to 3,
+             as the resulting average does not evolve significantly afterward.
+         

+         

+             Only a global scaling is allowed, and not 3 different scalings for
+             each axis. We want to average the shape of the heads, and
+             having different factors in x, y or z does alter the original
+             shape. Plus, it would make the whole process very dependent to which
+             file is picked in the first stage.
+         

+         

+             How to run the averaging
+         

+         

+             Called from the 
+                 
+                     Tools
+                     | Averaging Electrodes Coordinates
+                 
+              menu, you simply have
+             to follow these steps (no dialog for the moment):
+         

+         
    
+             
  • 
+                 
    
+                     Give the list of files to be averaged;
+                 
    
+             
  • 
+                 
    
+                     Give the output file name;
+                 
    
+             
  • 
+                 
    
+                     Provide the Cz, Fpz and Oz approximate locations
+                 
    
+                 
    
+                     (you can specify up to 4 electrodes for each locus, like "125
+                     138 137", to use their average position).
+                 
    
+             
  • 
+                 
    
+                     The process begins straight away. At the end, it can burps a few
+                     error messages that are worth reading, usually indicating that the
+                     result is somehow unreliable and some files to be excluded.
+                 
    
+         

+         

+             Input files
+         

+         

+             The files to be averaged should be taken from the 
+                 same
+                 source/process of measurement:
+             
+         

+         
    
+             
  • 
+                 
    
+                     They should have the same orientation (though it can be arbitrary),
+                 
    
+             
  • 
+                 
    
+                     the same number of electrodes (!),
+                 
    
+             
  • 
+                 
    
+                     but centers, scalings and some rotations are allowed (and expected),
+                     and can be arbitrary.
+                 
    
+         

+         

+             Cz / Fpz / Oz locations
+         

+         

+             See here an example for specifying Fpz, as we gave the electrodes 25
+             26 and 32, so to have Fpz in the middle of these 3 points:
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+             Results
+         

+         

+             Here are the output files:
+         

+         
    
+             
  • 
+                 
    
+                     All files will begin with the output file given;
+                 
    
+             
  • 
+                 
    
+                     A .xyz file for the
+                     average electrodes;
+                 
    
+             
  • 
+                 
    
+                     A .Distances.sef
+                     file for the distances to the final average
+                 
    
+             
  • 
+                 
    
+                     A .vrb verbose file.
+                 
    
+         

+         

+              
+         

+         

+             To help visualize, see here 3 coregistered files (blue meshes &
+             electrodes) on top of the final average (yellow triangles):
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+              
+         

+         

+             Distance file
+         

+         

+             It indicates the distance of each file to the average, for each
+             electrode (distance from the blue electrodes to the yellow ones in
+             the figure above). The Y axis are the electrodes, and the X axis is
+             the index of each of the original files.
+         

+         

+             Plus, there are 2 more positions in X ("files"):
+         

+         
    
+             
  • 
+                 
    
+                     The average of the distances, per electrode, across all files.
+                 
    
+                 
    
+                     This measure is equivalent to a Mean Absolute Deviation, and
+                     measures the distance from the data set to the average.
+                 
    
+             
  • 
+                 
    
+                     The dispersion of the distances, per electrode, across all files.
+                 
    
+                 
    
+                     This measure is a within group average distance (average of distances
+                     of all pairs of data), and measures the 
+                         variability of the
+                         coregistered data
+                     .
+                 
    
+                 
    
+                     Note that the SD of the distance to the average is not a very
+                     interesting measure here: if all files are all wrong but within an
+                     equal range, the SD would be low anyway, even though the coregistered
+                     data being far.
+                 
    
+         

+         

+              
+         

+         

+             You can of course link this distance
+             file with the average .xyz to visualize the results,
+             here we can see the average of electrodes distances:
+         

+         
    
+             
    
+                 
+             
    
+         

+         

+             Verbose file
+         

+         

+             It contains all the input parameters, the content of the distance
+             file plus some more details.
+         

+         

+             In addition to the distance, you will find 2 more rows (in Y):
+         

+         
    
+             
  • 
+                 
    
+                     The average of the distances, per file, across all electrodes,
+                 
    
+                 
    
+                     including on the last 2 columns the average of average of distances,
+                     and the average of dispersion.
+                 
    
+             
  • 
+                 
    
+                     The Coefficient of Variation of the distances (CoV, normalized
+                     SD/Avg), per file, across all electrodes,
+                 
    
+                 
    
+                     including on the last 2 columns the CoV of the average (not
+                     the average of the CoV) and the CoV of dispersion.
+                 
    
+         

+         

+              
+         

+         

+             Error messages
+         

+         

+             The error messages you might have had at the end of the processing
+             are also reproduced into the verbose file, so you can have a second
+             thought on them:
+         

+         
    
+             
  • 
+                 
    
+                     It could be that a file is considered globally unfit to the average,
+                     by comparing the average distance across all the electrodes, to the
+                     average of average of distances.
+                 
    
+             
  • 
+                 
    
+                     Or it could be that 
+                         some electrodes of a file are considered
+                         locally unfit to the average
+                     , by comparing its CoV of all
+                     electrodes to about 52%.
+                 
    
+         

+         

+             The advice is to first remove the files of the first category, run
+             again the averaging, then only remove the files of the second
+             category, if there remain some anymore.
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+     

  
 
\ No newline at end of file
diff --git a/docs/ReferenceGuide/eeg-display.html b/docs/ReferenceGuide/eeg-display.html
index 35919971..35cf1b9a 100644
--- a/docs/ReferenceGuide/eeg-display.html
+++ b/docs/ReferenceGuide/eeg-display.html
@@ -31,2878 +31,3931 @@
 }
 
  
- 
-  

-   EEG Display

-  

-   Buttons

-  

-      

-  

-    

-  

-     

-  

-     

-  

-       

-  

-    

-  

-    

-  

-    

-  

-      

-  

-   Mouse

-  

-   Chart of all mouse operations

-   Time selection

-   Tracks selection

-   Bad tracks selection

-   Horizontal scrolling  or  
-   Next / Previous tracks
Horizontal  or  vertical zoom

-   Relative vertical zoom

-   Keep current sub-window

-   Drag & Drop

-  

-   Keyboard

-  

-   Moving the cursor

-   Next  or  previous page

-   Beginning  or  end of Eeg

-   Quickly creating markers

-   Quickly jumping the cursor by blocks

-  

-   Menus

-  

-   Edit

-  

-   Selection

-  
-  

-   Markers

-  
-  

-   Options

-  
    
-   
    
-    Reference
    Time
    Set Display Scaling
    Set Time Window
    Reset Tracks Scaling
    Specify a  Baseline Offset
    Reset Baseline Offset
    Line Width
    Show / Hide Baseline Axis
    Goto Another Session / Block
    
-   

-  

-   EEG - Buttons

-  

-   Go here for the buttons 
-   common to all views.

-  

-   Linking to other Eegs  

-  

-   The way to proceed is the very same as for any standard
-    view, but the targeted windows are exclusively restricted to other
-    Eegs only. The link behavior is also slightly different from the 
-   standard link which is purely graphical. Here the window owner of the 
-   links will load the external data, use them as its own 
-   to superimpose them. If the user changes the number of tracks, 
-   scalings etc..., all linked data will also move accordingly (except 
-   filtering, which is still the sole responsability of each individual 
-   Eeg). Here is an example with 2 Eegs:

-  

-   linked
-    by=

-  

-   Changing the number of tracks will naturally affect all the linked 
-   Eegs (here with 3 Eegs):

-  

-   

-  

-   The color scheme for the linked tracks is the following: black, red, 
-   green, blue, cyan, magenta, yellow, then again these 7 colors in 
-   dashed, then cycles back to black, red, green, etc... You may find 
-   useful to also change the line width of the 
-   plotting to improve clarity.

-  

-   Another point. Though Eeg views can only link to other Eeg views, 
-   non-Eeg views can link to Eeg views, so you can have this kind 
-   of display (a scalp potentials linking to a 3D
-    view of its tracks):

-  

-   

-  

-   Rendering  

-  

-   (Go here for basic explanations on rendering)

-   Toggles between 3 or 5 display modes:

-  
    
-   
  • 
-   
    
-    Default mode, a 2 parts display showing the regular
-     tracks above, and some (if any) computed
-     tracks below:
    
-   
    
-    
    
-   
  • 
-   
    
-    Split mode, a 4 / 8 parts display showing half / fourth of the 
-    current displayed tracks on each side, while repeating the computed 
-    tracks each time. Adding or removing some tracks will automatically 
-    be reflected in the splitting:
    
-   
    
-    
    
-   
  • 
-   
    
-    Each track is assigned an "individual box", and all 
-    the boxes will be optimally packed inside the current window. 
-    Changing the number of tracks displayed, or the shape of the window 
-    will affect the distribution of these boxes (just try it):
    
-   
    
-    
    
-   

-  

-   If the Eeg has been linked 
-   with some electrodes coordinates, that is, if geometrical 
-   information is available, the following 2 modes are also available.

-  
    
-   
  • 
-   
    
-    Each track is also in a box, as seen above, but the boxes are 
-    positionned according to the projected locations of the electrodes:
    
-   
    
-    
    
-   
  • 
-   
    
-    Same as above, but the tracks are rendered 
-    in 3D:
    
-   
    
-    
    
-   
    
-    This is the only real 3D mode available for an Eeg display, 
-    which therefore brings you with all the Standard
-     3D commands (mouse interaction and so on...).
    
-   

-  

-    

-  

-   Tracks / Bars / Intensity display 
-    

-  

-   This button lets use choose between Tracks (line plots), Bars 
-   (filled) and Intensity (colors) displays:

-  

-   

-  

-   Showing the Regions Of Interest  

-  

-   This button is enabled if a .rois 
-   file is available in the link
-    many file, and the dimension of the rois is equal to the number
-    of electrodes.

-  

-   Pressing this button will cycle within all possible rois listed in 
-   the link many file. Once a roi is active, the tracks are grouped by 
-   each roi. And within each roi, tracks are also re-ordered, which 
-   could be a convenient way to reorganize tracks on the display!

-  

-    

-  

-   Here is an example of 4 rois shown simultaneously; and then when only
-    one roi is selected, with the tracks within it appearing re-ordered 
-   (according to the ROIs file):

-  

-   

-  

-    

-  

-   The .ris files 
-   can, too, benefit from the ROIs, resulting in a far cleaner display. 
-   In this case, just provide the ROIs
-    for Inverse Solutions:

-  

-   

-  

-   You might be interested to learn how to create
-    the rois file, too?

-  

-   Averaging ROIs  

-  

-   If some rois are currently active, this will average
-    all the tracks of each roi.

-  

-   All the computations run first as usual (reference, filters, etc...), 
-   and only at the end the tracks belonging to the same region are 
-   averaged. All tracks of a given region will then receive the same 
-   averaged value:

-  

-   

-  

-   See also the resulting maps 
-   of averaged rois.

-  

-   Show triggers and markers  

-  

-   Turns on and off the display of both the triggers 
-   and the markers (see the specific menu 
-   for the markers). Triggers/markers are drawn in green in the Eeg 
-   display, with their descriptions on upper right.

-  

-   Previous trigger  

-  

-   Set cursor position to the previous 
-   visible marker.

-  

-   Next trigger  

-  

-   Set cursor position to the next 
-   visible marker.

-  

-   Add a marker  

-  

-   Add a marker from the current cursor 
-   position, even if it is extended. Markers can overlap, but in this 
-   case they should differ at least either by their beginnings or their 
-   endings. Otherwise (i.e. they are equal) the old one will be overwritten.

-  

-   Set the current marker description that will be used through the 
-   marker menu.

-  

-   Extend cursor  

-  

-   Usually, it works automatically when setting the cursor with the mouse,
-    you can see it toggling on and off.

-  

-   However, it can be sometime very useful to proceed another way:

-  
    
-   
  • 
-   
    
-    click on the button, or rather press the space bar (it toggles 
-    the button on)
    
-    
  • extend the cursor with the left and right 
-    arrows (do not use the mouse)
    
-    
  • when done, click again on the button, or press 
-    again the space bar (toggles it off)
    
-   

-  

-   Just be careful to close this mode, or your cursor is still 
-   "open" to modifications (which you might want, by the way)

-  

-   Show upper tracks  

-  

-   When only a few tracks are on display, this button shifts to 
-   "upper"/previous tracks, adding one track at a time. If 
-   holding Shift down, it will shift for the actual number of 
-   tracks at each time.

-  

-   Show tracks below  

-  

-   The same as previous, in the opposite direction.

-  

-   Selecting a session  

-  

-   This button is activated when the recording has many sessions into it 
-   (which I don't recommend nor understand, why not write a NEW file 
-   each time?). In this case, clicking on it will bring a dialog asking 
-   which session to open, starting from 1 to n. The current 
-   window will close, and reopen a fresh window of the 
-   requested session.

-  

-   Less tracks  

-  

-   Removes some tracks from display, 
-   starting with the last ones. Or if some tracks are currently selected,
-    these will be removed.

-  

-   More Tracks  

-  

-   Brings back some tracks on display, 
-   first adding after the last ones, then filling any gaps between the 
-   first and the last of the current display.

-  

-   Less computed tracks  

-  

-   Removes some computed tracks from the 
-   display, starting with the last ones. Or if some computed tracks are 
-   currently selected, these will be removed.

-  

-   More computed tracks  

-  

-   Gets back some computed tracks from 
-   the display, starting with the last ones.

-  

-   Superimpose tracks  

-  

-   Superimposes current regular tracks.

-  

-   When shrinking to a too small window, Cartool will superimpose tracks 
-   by itself to keep a clear display. In this case, it will also 
-   superimposes the computed tracks. At that time, toggling on or off 
-   this button will have no effect, except when expanding back the 
-   window to a regular size.

-  

-   Reverse displayed polarity  

-  

-   Vertically reverses the display, showing the negative values above 
-   the 0, the positive values below 0. Just the display, not the data 
-   (it seems some people like it, in the south hemisphere maybe? 8).

-  

-   Show standard deviation  

-  

-   This button is enabled when a file is found within the same 
-   directory, with the very same name, but with extension .epsd 
-   (standard deviation) or .epse (standard error). This detection 
-   is automatic.

-  

-   This is a 3 states button:

-  
    
-   
  • 
-   
    
-    no standard deviation shown
    
-    
  • standard deviation is drawn with dashed lines
    
-    
  • standard deviation is filled with transparent color
    
-   

-  

-   Increase vertical scaling  

-  

-   Or vertical zoom in, makes the tracks amplitude bigger. See also mouse
-    operations and the relative 
-   mouse rescaling.

-  

-   Decrease vertical scaling  

-  

-   Or vertical zoom out, makes the tracks amplitude smaller. See also mouse
-    operations and the relative 
-   mouse rescaling.

-  

-   Increase horizontal scaling  

-  

-   Or horizontal zoom in, makes the time interval smaller. See also mouse
-    operations.

-  

-   Decrease horizontal scaling  

-  

-   Or horizontal zoom out, makes the time interval bigger. See also mouse
-    operations.

-  

-   Show amplitude units  

-  

-   Draws the vertical units behind the tracks. If the tracks are too 
-   much packed, you actually won't see any effect. There should be some 
-   space in between the tracks, so select the one you are interested in, 
-   or superimpose them. Then, by 
-   changing the vertical scaling you 
-   can see the scaling adapting itself to the data.

-   Tracks with different units or scales, like GFP 
-   and Dissimilarity, have each a 
-   separate and different scaling used.

-  

-   Show time units  

-  

-   Draws time intervals behind the tracks, the space between them 
-   depending on the current horizontal scaling.
-    The intervals are in milliseconds, starting from the beginning of 
-   the file, but if the Eeg has no sampling frequency value available, 
-   the intervals are simply put in time frames.

-  

-   Filters  

-  

-   Brings up the dialog with all the available filters:

-  

-   

-    

-   

-  

-   
-    
-     
-     
-    
-       
-     
-     
-       
-       
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-       
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-       
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-    
-     
-     
-    
-       
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-   

-      

-       Filters

-      

-        

-      

-       DC / Baseline Removal

-      

-       Remove the DC, or 0 Hz.

-	  

-       The time interval used to compute the DC depends on the 
-	   context:

-	  
    
-		  
  •  Within an EEG display, the current page is used.
    • 
-		  
  • During Export Tracks, the whole 
-		  file is being used.
    • 
-	  

-      

-       The DC Removal button is automatically selected when High Pass 
-       filtering is set, as to prevent well-known instabilities from the 
-	   Butterworth (IIR) filter. Still, you can turn it off manually.

-      

-       You can also use it independently of the High Pass filter, just to 
-       quickly remove the baseline of the current displayed window.

-      

-       Butterworth
-       High Pass:

-      

-       Specify the cut-off frequency, in Herz. 
-	   See here for more details when combining with the Low Pass.

-      

-       The time interval used for the high-pass depends on the 
-	   context:

-	  
    
-		  
  •  Within an EEG display, the current page is used plus some 
-		  left and right margin. The margin being equal to half the 
-		  wavelength of the cut-off frequency. F.ex. 1 Hz gives 500 ms.
    • 
-		  
  • During Export Tracks, the whole 
-		  file is being used.
    • 
-	  

-		

-      

-       Order (even, in [2..64]):

-      

-       Order of the Butterworth High Pass.

-	  

-       Higher order filters perform better in terms of keeping the desired 
-	   frequencies and rejecting the unwanted ones. This comes at the cost of 
-	   more processing, and possible instabilities for difficult data.

-	  

-       Due to current optimal implementations, order must be an even 
-	   number, and is currently limited to the range [2..64].

-		

-      

-       Butterworth
-       Low Pass:

-      

-       Specify the cut-off frequency, in Herz. 
-	   See here for more details when combining with the High Pass.

-	  

-       The time interval used for the low-pass depends on the 
-	   context:

-	  
    
-		  
  •  Within an EEG display, the current page is used plus some 
-		  left and right margin. The margin being equal to twice the 
-		  wavelength of the cut-off frequency. F.ex. 40 Hz gives 50 ms.
    • 
-		  
  • During Export Tracks, the whole 
-		  file is being used.
    • 
-	  

-		

-      

-       Order (even, in [2..64]):

-      

-       Order of the Butterworth Low Pass.

-	  

-       Higher order filters perform better in terms of keeping the desired 
-	   frequencies and rejecting the unwanted ones. This comes at the cost of 
-	   more processing, and possible instabilities for difficult data.

-	  

-       Due to current optimal implementations, order must be an even 
-	   number, and is currently limited to the range [2..64].

-		

-      

-       Butterworth Filters Causality:

-      

-        

-	  	 

-      

-       Causal (forward ony)

-      

-       When set, this forces the filters to work as in a real-life recording 
-	   machine. It filters by making use of 
-	   data known so far, that is, "from the past and present". 
-	   Problem is the filtered signal has now some time delay.

-		   

-      

-       Non-Causal (forward and backward)

-      

-       When set (default), filters make use 
-	   of all available data by applying the filters twice, once forward and 
-	   once backward. The nice property is that it totally restores 
-	   the time accuracy.

-		   

-      

-       Butterworth Notch(es):

-      

-       One or more notch values, in Herz.

-      

-       As hinted, Notch filtering is done with a Butterworth Bandstop 
-	   filter of order 12, and a stopband of 1Hz.

-      

-       + All Harmonics

-      

-       With this option, Cartool will add all the harmonics from the 
-	   list of notch frequencies above, up to the Nyquist limit. This 
-	   way you save typing them yourselves, with the risk of missing some of 
-	   them. And it automatically adapts the bank of filters to the actual 
-	   sampling frequency.

-       F.ex. filtering some 50Hz power line noise with this option will filter 
-	   out (assuming 1000Hz sampling frequency here):
    
-		  
  • 50Hz fundamental
    • 
-		  
  • 100, 150, 200, 250, 300, 350, 400, 450 and 500Hz 
-		  harmonics
    • 
-	  

-	  

-        

-       You can opt out this option to have finer control of your series of notch 
-	   filters if you wish so. But be aware that even if you Low Pass to 40Hz 
-	   f.ex., many frequencies well above 40Hz will still be present and will 
-	   need some actions.

-      

-       Spatial Filter:

-      

-       Applying the Spatial Filter 
-	   to the data.

-       Drag & Drop or click Browse to select an appropriate
-	   electrodes coordinates 
-	   file.

-      

-       Ranking

-      

-       Rank the data. At each time frame, electrode values are sorted, and the 
-	   data is then replaced with their ranks.

-       Results are normalized with the number of electrodes, the results 
-	   therefor being in the range [0..1] (0 for the lowest value, 1 for the 
-	   highest value).

-      

-       <Reference computation here>

-      

-       This is just to formally show where Cartool computes the reference, so 
-	   just after the filters above. The next filters will use the optionally 
-	   re-referenced data.

-      

-       Rectification:

-      

-       Making the data all positive.

-       Usually a step before the Envelop filter below, but it can also be 
-	   interesting sometimes to force the data to absolute.

-      

-       Absolute value

-      

-       Absolute of input value.

-      

-       Squared value (Power)

-      

-       Squared of input value, therfor equivalent to a power. Of course, results 
-	   are positive...

-      

-       + Envelope, of window duration:

-      

-       Compute the Envelope, a kind of fast frequency analysis.

-       To be able to compute the Envelope, all these points must be fulfilled:
    
-		  
  • High- and Low-pass filters should be set
    • 
-		  
  • Some Rectification (button above) should be set
    • 
-		  
  • A sliding-window duration must be specified.
    The suggested 
-		  window size is  1.5 / LowFreq
    • 
-	  

-		

-      

-       Thresholding, keeping Above:

-      

-       Cutting the data at the specified threshold, keeping the values 
-	   above.

-      

-       Thresholding, keeping Below:

-      

-       Cutting the data at the specified threshold, keeping the values 
-	   below.

-	  

-       Both Above and Below options can be used at the same time. 
-	   In that case remaining values are both above and below 
-	   the specified thresholds (interval).

-      

-       Options

-      

-        

-      

-       Sampling Frequency (set if missing):

-      

-       If the current file has a sampling frequency, its value will be shown here.

-      

-       If not, the field is editable, and it is mandatory to have a value 
-       entered to be able to apply any of the filters.

-      

-       Also apply filters to:

-      

-       Auxiliaries Channels

-      

-       Specifies if the auxiliary electrodes are to be filtered.

-      

-       Switch On / Off all filters set

-      

-       You can turn on and off all the currently entered filters. This is 
-       very convenient to see the effects of a set of filters, by simply 
-       turning the filtering on and off.

-      

-       OK

-      

-       Accept the filters.

-      

-       This button remains disabled until all the parameter 
-       dialogs have received enough (and consistent) informations. If 
-       this is not the case, first check the current dialog: if its 
-       "Next" button is disabled, the problem is in the current 
-       dialog. Otherwise, browse the other dialogs for some missing informations.

-      

-       Cancel

-      

-       Quit the dialog, and remain in the previous filtering state.

-      

-       Help

-      

-       Launch the Help to the right page (should be here...).

-  

-    

-  

-   Filters combination and sequence

-  

-   Filters are applied sequentially, following the top-down design of 
-   the dialog. This means DC filter is first to be applied, then the 
-   Butterworth, then the Spatial Filter and so on and so forth. Most of these 
-   filters are not linearly permutables, which means the actual sequence 
-   does matter a lot on your results! The current sequence is the results 
-   of 25+ years of experience in the field.

-  

-    

-  

-   When applying both the Butterworth High Pass and the 
-   Butterworth Low Pass filters, they will be automatically merged into 
-   a single Butterworth Bandpass filter (instead of running 
-   these two filters sequentially):

-  
    
-	  
  • Order of the Bandpass will be the sum of 
-	  orders from the 2 single Butterworth filters.
    F.ex. if High 
-	  and Low passes have each an order of 4, then the 
-	  resulting Bandpass will have order of 2x4=8.
    This 
-	  makes the final Bandpass filter orders to be multiples of 4.
    • 
-	  
  • Bandpass will therefore be two times more powerful than the single 
-	  filters alone, due to the doubling of order.
    • 
-  

-  

-    

-  

-   Filtering only affects the display in real-time, and does not 
-   alter the original data. To permanently change the 
-   data, you can either call File | Save As, 
-   or go through the more versatile Export
-    Tracks toolbox.

-  

-   Filter causality

-  

-   Sometimes, one needs to control how the filters make use of "data from the 
-   future", so to speak.

-  

-   A filter that receives data only from the past and present is said to be 
-   causal, and non-causal if it makes use of data from the future. The latter 
-   case can only happen once the recording has been done. It is done by applying 
-   the filter once forward, then again once backward.

-  

-    

-  

-   Non-causal filter

-  

-   The enormous advantage of the non-causal filtering for EEG analysis is that
-   it restores the phases of the original signal. This means
-   peaks' locations remain stable. It also restores the phases 
-   for all frequencies, so the reconstructed signal also corresponds to the 
-   original one, minus the removed frequencies of course. It is the default 
-   option, and is widely used in the EEG community.

-  

-   Note: when applying twice a filter, the decay at 
-   cut-off frequency will no longer be -3dB (filter has been applied twice!). 
-   Cartool counteracts this effect internally by operating a slight adjustment 
-   to the cut-off frequency, so that the double-filtering has an actual -3dB 
-   decay at cut-off.

-  

-    

-  

-       Causal filter

-  

-       This can be used if one wants to make sure no data from the future might 
-	   have back-propagated and caused possible interference with the results. 
-	   This option is to be used mainly for picky reviewers... Note that all 
-	   real-time implementations like a recording machine must use a causal 
-	   filter - if any.

-  

-       One big disadvantage a causal filter is the delay added to the 
-	   resulted filtered signal. Peaks locations are no longer at the 
-	   right time positions! An aggravated issue is that the phase shifts differ 
-	   at each frequency, slightly "scrambling" the data.

-  

-   Pamphlet you can include for publications

-  

-   Here is the technical pamphlet for a single Butterworth filter, 
-   replacing <actualorder> by the order used in the dialog:

-  

-   The Butterworth Low / High pass filters are 
-   <actualorder> order filters, with <-20 x actualorder> dB/decade roll-off 
-   and maximally flat response. They are implemented as cascaded 2nd 
-   order sections with bilinear transform, and applied twice with one forward 
-   and one backward pass to eliminate the phase shift.

-  

-   When both High Pass and Low Pass 
-   filters are applied, it ends up with a Butterworth 
-   Bandpass - note the doubling order from the dialog numbers:

-  

-   The Butterworth Bandpass filter is a <2 x actualorder> 
-   order filter, with <-40 x actualorder> dB/decade roll-off and 
-   maximally flat response. It is implemented as cascaded 2nd order 
-   sections with bilinear transform, and applied twice with one forward and one 
-   backward pass to eliminate the phase shift.

-  

-   The Notch filter is implemented as a Butterworth Bandstop 
-   filter - note the optional part if you selected All Harmonics:

-  

-   The Notch filter is implemented as a Butterworth Bandstop filter 
-   of order 12, with -240 dB/decade roll-off and maximally flat response, and a 
-   stopband of 1Hz. It is implemented as cascaded 2nd order sections 
-   with bilinear transform, and applied twice with one forward and one backward 
-   pass to eliminate the phase shift. <optional part> Harmonic 
-   frequencies have also been filtered out with cascaded Notch filters, up to 
-   the Nyquist limit.

-  

-   Note that if you are going to comment on all these filters in the same 
-   section, you can shorten these pamphlet to avoid repeating the implementation 
-   details that are exactly identical.

-  

-    

-  

-   Reference

-  
Reference used for the implementation of the Butterworth filters:

-  
"Recursive Digital Filters - A Concise Guide",
+ 
+     

+         

+             EEG Display
+         

+         

+             Buttons
+         

+         

+                
+         

+         

+              
+         

+         

+               
+         

+         

+               
+         

+         

+                 
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+                
+         

+         

+             Mouse
+         

+         

+             Chart of all mouse operations

+             Time selection

+             Tracks selection

+             Bad tracks selection

+             
+                 Horizontal scrolling  or 
+                 Next / Previous tracks
+             
Horizontal  or  vertical zoom

+             Relative vertical zoom

+             Keep current sub-window

+             Drag & Drop
+         

+         

+             Keyboard
+         

+         

+             Moving the cursor

+             Next  or  previous page

+             Beginning  or  end of Eeg

+             Quickly creating markers

+             Quickly jumping the cursor by blocks
+         

+         

+             Menus
+         

+         

+             Edit
+         

+         

+             Selection
+         

+         
+         

+             Markers
+         

+         
+         

+             Options
+         

+         
    
+             
    
+                 Reference
    Time
    Set Display Scaling
    Set Time Window
    Reset Tracks Scaling
    Specify a  Baseline Offset
    Reset Baseline Offset
    Line Width
    Show / Hide Baseline Axis
    Goto Another Session / Block
+             
    
+         

+         

+             EEG - Buttons
+         

+         

+             Go here for the buttons
+             common to all views.
+         

+         

+             Linking to other Eegs  
+         

+         

+             The way to proceed is the very same as for any 
+                 standard
+                 view
+             , but the targeted windows are exclusively restricted to 
+                 other
+                 Eegs only
+             . The link behavior is also slightly different from the
+             standard link which is purely graphical. Here the window owner of the
+             links will load the external data, use them as its own
+             to superimpose them. If the user changes the number of tracks,
+             scalings etc..., all linked data will also move accordingly (except
+             filtering, which is still the sole responsability of each individual
+             Eeg). Here is an example with 2 Eegs:
+         

+         

+             linked
+             by=
+         

+         

+             Changing the number of tracks will naturally affect all the linked
+             Eegs (here with 3 Eegs):
+         

+         

+             
+         

+         

+             The color scheme for the linked tracks is the following: black, red,
+             green, blue, cyan, magenta, yellow, then again these 7 colors in
+             dashed, then cycles back to black, red, green, etc... You may find
+             useful to also change the line width of the
+             plotting to improve clarity.
+         

+         

+             Another point. Though Eeg views can only link to other Eeg views,
+             non-Eeg views can link to Eeg views, so you can have this kind
+             of display (a scalp potentials linking to a 
+                 3D
+                 view
+              of its tracks):
+         

+         

+             
+         

+         

+             Rendering  
+         

+         

+             (Go here for basic explanations on rendering)

+             Toggles between 3 or 5 display modes:
+         

+         
    
+             
  • 
+                 
    
+                     Default mode, a 2 parts display showing the 
+                         
+                             regular
+                             tracks
+                         
+                      above, and some (if any) 
+                         
+                             computed
+                             tracks
+                         
+                      below:
+                 
    
+                 
    
+                     
+                 
    
+             
  • 
+                 
    
+                     Split mode, a 4 / 8 parts display showing half / fourth of the
+                     current displayed tracks on each side, while repeating the computed
+                     tracks each time. Adding or removing some tracks will automatically
+                     be reflected in the splitting:
+                 
    
+                 
    
+                     
+                 
    
+             
  • 
+                 
    
+                     Each track is assigned an "individual box", and all
+                     the boxes will be optimally packed inside the current window.
+                     Changing the number of tracks displayed, or the shape of the window
+                     will affect the distribution of these boxes (just try it):
+                 
    
+                 
    
+                     
+                 
    
+         

+         

+             If the Eeg has been 
+                 linked
+                 with some electrodes coordinates
+             , that is, if geometrical
+             information is available, the following 2 modes are also available.
+         

+         
    
+             
  • 
+                 
    
+                     Each track is also in a box, as seen above, but the 
+                         boxes are
+                         positionned according to the projected locations of the electrodes
+                     :
+                 
    
+                 
    
+                     
+                 
    
+             
  • 
+                 
    
+                     Same as above, but the tracks are rendered
+                     in 3D:
+                 
    
+                 
    
+                     
+                 
    
+                 
    
+                     This is the only real 3D mode available for an Eeg display,
+                     which therefore brings you with all the 
+                         
+                             Standard
+                             3D commands
+                         
+                      (mouse interaction and so on...).
+                 
    
+         

+         

+              
+         

+         

+             Tracks / Bars / Intensity display 
+             
+         

+         

+             This button lets use choose between Tracks (line plots), Bars
+             (filled) and Intensity (colors) displays:
+         

+         

+             
+         

+         

+             Showing the Regions Of Interest  
+         

+         

+             This button is enabled if a .rois
+             file is available in the 
+                 link
+                 many file
+             , and the dimension of the rois is equal to the 
+                 number
+                 of electrodes
+             .
+         

+         

+             Pressing this button will cycle within all possible rois listed in
+             the link many file. Once a roi is active, the tracks are grouped by
+             each roi. And within each roi, tracks are also re-ordered, which
+             could be a convenient way to reorganize tracks on the display!
+         

+         

+              
+         

+         

+             Here is an example of 4 rois shown simultaneously; and then when 
+                 only
+                 one roi
+              is selected, with the tracks within it appearing re-ordered
+             (according to the ROIs file):
+         

+         

+             
+         

+         

+              
+         

+         

+             The .ris files
+             can, too, benefit from the ROIs, resulting in a far cleaner display.
+             In this case, just provide the 
+                 ROIs
+                 for Inverse Solutions
+             :
+         

+         

+             
+         

+         

+             You might be interested to learn how to 
+                 create
+                 the rois file
+             , too?
+         

+         

+             Averaging ROIs  
+         

+         

+             If some rois are currently active, this will 
+                 average
+                 all the tracks of each roi
+             .
+         

+         

+             All the computations run first as usual (reference, filters, etc...),
+             and only at the end the tracks belonging to the same region are
+             averaged. All tracks of a given region will then receive the same
+             averaged value:
+         

+         

+             
+         

+         

+             See also the resulting maps
+             of averaged rois.
+         

+         

+             Show triggers and markers  
+         

+         

+             Turns on and off the display of both the triggers
+             and the markers (see the specific menu
+             for the markers). Triggers/markers are drawn in green in the Eeg
+             display, with their descriptions on upper right.
+         

+         

+             Previous trigger  
+         

+         

+             Set cursor position to the previous
+             visible marker.
+         

+         

+             Next trigger  
+         

+         

+             Set cursor position to the next
+             visible marker.
+         

+         

+             Add a marker  
+         

+         

+             Add a marker from the current cursor
+             position, even if it is extended. Markers can overlap, but in this
+             case they should differ at least either by their beginnings or their
+             endings. Otherwise (i.e. they are equal) the old one will be overwritten.
+         

+         

+             Set the current marker description that will be used through the
+             marker menu.
+         

+         

+             Extend cursor  
+         

+         

+             Usually, it works automatically when setting the cursor with the mouse,
+             you can see it toggling on and off.
+         

+         

+             However, it can be sometime very useful to proceed another way:
+         

+         
    
+             
  • 
+                 
    
+                     click on the button, or rather press the space bar (it toggles
+                     the button on)
    
+             
  • 
+                 extend the cursor with the left and right
+                 arrows (do not use the mouse)
    
+             
  • 
+                 when done, click again on the button, or press
+                 again the space bar (toggles it off)
    
+         

+         

+             Just be careful to close this mode, or your cursor is still
+             "open" to modifications (which you might want, by the way)
+         

+         

+             Show upper tracks  
+         

+         

+             When only a few tracks are on display, this button shifts to
+             "upper"/previous tracks, adding one track at a time. If
+             holding Shift down, it will shift for the actual number of
+             tracks at each time.
+         

+         

+             Show tracks below  
+         

+         

+             The same as previous, in the opposite direction.
+         

+         

+             Selecting a session  
+         

+         

+             This button is activated when the recording has many sessions into it
+             (which I don't recommend nor understand, why not write a NEW file
+             each time?). In this case, clicking on it will bring a dialog asking
+             which session to open, starting from 1 to n. The current
+             window will close, and reopen a fresh window of the
+             requested session.
+         

+         

+             Less tracks  
+         

+         

+             Removes some tracks from display,
+             starting with the last ones. Or if some tracks are currently selected,
+             these will be removed.
+         

+         

+             More Tracks  
+         

+         

+             Brings back some tracks on display,
+             first adding after the last ones, then filling any gaps between the
+             first and the last of the current display.
+         

+         

+             Less computed tracks  
+         

+         

+             Removes some computed tracks from the
+             display, starting with the last ones. Or if some computed tracks are
+             currently selected, these will be removed.
+         

+         

+             More computed tracks  
+         

+         

+             Gets back some computed tracks from
+             the display, starting with the last ones.
+         

+         

+             Superimpose tracks  
+         

+         

+             Superimposes current regular tracks.
+         

+         

+             When shrinking to a too small window, Cartool will superimpose tracks
+             by itself to keep a clear display. In this case, it will also
+             superimposes the computed tracks. At that time, toggling on or off
+             this button will have no effect, except when expanding back the
+             window to a regular size.
+         

+         

+             Reverse displayed polarity  
+         

+         

+             Vertically reverses the display, showing the negative values above
+             the 0, the positive values below 0. Just the display, not the data
+             (it seems some people like it, in the south hemisphere maybe? 8).
+         

+         

+             Show standard deviation  
+         

+         

+             This button is enabled when a file is found within the same
+             directory, with the very same name, but with extension .epsd
+             (standard deviation) or .epse (standard error). This detection
+             is automatic.
+         

+         

+             This is a 3 states button:
+         

+         
    
+             
  • 
+                 
    
+                     no standard deviation shown
    
+             
  • standard deviation is drawn with dashed lines
    
+             
  • standard deviation is filled with transparent color
    
+         

+         

+             Increase vertical scaling  
+         

+         

+             Or vertical zoom in, makes the tracks amplitude bigger. See also 
+                 mouse
+                 operations
+              and the 
+                 
+                     relative
+                     mouse rescaling
+                 
+             .
+         

+         

+             Decrease vertical scaling  
+         

+         

+             Or vertical zoom out, makes the tracks amplitude smaller. See also 
+                 mouse
+                 operations
+              and the 
+                 
+                     relative
+                     mouse rescaling
+                 
+             .
+         

+         

+             Increase horizontal scaling  
+         

+         

+             Or horizontal zoom in, makes the time interval smaller. See also 
+                 mouse
+                 operations
+             .
+         

+         

+             Decrease horizontal scaling  
+         

+         

+             Or horizontal zoom out, makes the time interval bigger. See also 
+                 mouse
+                 operations
+             .
+         

+         

+             Show amplitude units  
+         

+         

+             Draws the vertical units behind the tracks. If the tracks are too
+             much packed, you actually won't see any effect. There should be some
+             space in between the tracks, so select the one you are interested in,
+             or superimpose them. Then, by
+             changing the vertical scaling you
+             can see the scaling adapting itself to the data.

+             Tracks with different units or scales, like GFP
+             and Dissimilarity, have each a
+             separate and different scaling used.
+         

+         

+             Show time units  
+         

+         

+             Draws time intervals behind the tracks, the space between them
+             depending on the current horizontal scaling.
+             The intervals are in milliseconds, starting from the beginning of
+             the file, but if the Eeg has no sampling frequency value available,
+             the intervals are simply put in time frames.
+         

+         

+             Filters  
+         

+         

+             Brings up the dialog with all the available filters:
+         

+         

+             

+                 
+             

+         

+         

+             
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+             

+                         

+                             Filters
+                     

+                         

+                              
+                     

+                         

+                             DC / Baseline Removal
+                     

+                         

+                             Remove the DC, or 0 Hz.
+                         

+                         

+                             The time interval used to compute the DC depends on the
+                             context:
+                         

+                         
    
+                             
  •  Within an EEG display, the current page is used.
    • 
+                             
  • 
+                                 During Export Tracks, the whole
+                                 file is being used.
+                             
    • 
+                         

+                         

+                             The DC Removal button is automatically selected when High Pass
+                             filtering is set, as to prevent well-known instabilities from the
+                             Butterworth (IIR) filter. Still, you can turn it off manually.
+                         

+                         

+                             You can also use it independently of the High Pass filter, just to
+                             quickly remove the baseline of the current displayed window.
+                     

+                         

+                             
+                                 Butterworth
+                                 High Pass:
+                             
+                     

+                         

+                             Specify the cut-off frequency, in Herz. 
+                                 See here for more details when combining with the Low Pass
+                             .
+                         

+                         

+                             The time interval used for the high-pass depends on the
+                             context:
+                         

+                         
    
+                             
  • 
+                                  Within an EEG display, the current page is used plus some
+                                 left and right margin. The margin being equal to 
+                                     half the
+                                     wavelength
+                                  of the cut-off frequency. F.ex. 1 Hz gives 500 ms.
+                             
    • 
+                             
  • 
+                                 During Export Tracks, the whole
+                                 file is being used.
+                             
    • 
+                         

+                     

+                         

+                             Order (even, in [2..64]):
+                     

+                         

+                             Order of the Butterworth High Pass.
+                         

+                         

+                             Higher order filters perform better in terms of keeping the desired
+                             frequencies and rejecting the unwanted ones. This comes at the cost of
+                             more processing, and possible instabilities for difficult data.
+                         

+                         

+                             Due to current optimal implementations, 
+                                 order must be an even
+                                 number
+                             , and is currently limited to the range [2..64].
+                         

+                     

+                         

+                             
+                                 Butterworth
+                                 Low Pass:
+                             
+                     

+                         

+                             Specify the cut-off frequency, in Herz. 
+                                 See here for more details when combining with the High Pass
+                             .
+                         

+                         

+                             The time interval used for the low-pass depends on the
+                             context:
+                         

+                         
    
+                             
  • 
+                                  Within an EEG display, the current page is used plus some
+                                 left and right margin. The margin being equal to 
+                                     twice the
+                                     wavelength
+                                  of the cut-off frequency. F.ex. 40 Hz gives 50 ms.
+                             
    • 
+                             
  • 
+                                 During Export Tracks, the whole
+                                 file is being used.
+                             
    • 
+                         

+                     

+                         

+                             Order (even, in [2..64]):
+                     

+                         

+                             Order of the Butterworth Low Pass.
+                         

+                         

+                             Higher order filters perform better in terms of keeping the desired
+                             frequencies and rejecting the unwanted ones. This comes at the cost of
+                             more processing, and possible instabilities for difficult data.
+                         

+                         

+                             Due to current optimal implementations, 
+                                 order must be an even
+                                 number
+                             , and is currently limited to the range [2..64].
+                         

+                     

+                         

+                             Butterworth Filters Causality:
+                     

+                         

+                              
+                         

+                     

+                         

+                             Causal (forward ony)
+                     

+                         

+                             When set, this forces the filters to work as in a real-life recording
+                             machine. 
+                                 
+                                     It filters by making use of
+                                     data known so far, that is, "from the past and present"
+                                 .
+                             
+                             Problem is the filtered signal has now some time delay.
+                         

+                     

+                         

+                             Non-Causal (forward and backward)
+                     

+                         

+                             When set (default), 
+                                 
+                                     filters make use
+                                     of all available data by applying the filters twice, once forward and
+                                     once backward
+                                 
+                             . The nice property is that it totally restores
+                             the time accuracy.
+                         

+                     

+                         

+                             Butterworth Notch(es):
+                     

+                         

+                             One or more notch values, in Herz.
+                         

+                         

+                             As hinted, Notch filtering is done with a 
+                                 Butterworth Bandstop
+                                 filter of order 12, and a stopband of 1Hz
+                             .
+                     

+                         

+                             + All Harmonics
+                     

+                         

+                             With this option, Cartool will 
+                                 add all the harmonics from the
+                                 list of notch frequencies above
+                             , up to the Nyquist limit. This
+                             way you save typing them yourselves, with the risk of missing some of
+                             them. And it automatically adapts the bank of filters to the actual
+                             sampling frequency.
+                         

+                             F.ex. filtering some 50Hz power line noise with this option will filter
+                             out (assuming 1000Hz sampling frequency here):
    
+                                 
  • 50Hz fundamental
    • 
+                                 
  • 
+                                     100, 150, 200, 250, 300, 350, 400, 450 and 500Hz
+                                     harmonics
+                                 
    • 
+                             

+                         

+                              
+                         

+                             You can opt out this option to have finer control of your series of notch
+                             filters if you wish so. But be aware that even if you Low Pass to 40Hz
+                             f.ex., many frequencies well above 40Hz will still be present and will
+                             need some actions.
+                     

+                         

+                             Spatial Filter:
+                     

+                         

+                             Applying the Spatial Filter
+                             to the data.
+                         

+                             Drag & Drop or click Browse to select an appropriate
+                             
+                                 electrodes coordinates
+                                 file
+                             .
+                     

+                         

+                             Ranking
+                     

+                         

+                             Rank the data. At each time frame, electrode values are sorted, and the
+                             data is then replaced with their ranks.
+                         

+                             Results are normalized with the number of electrodes, the results
+                             therefor being in the range [0..1] (0 for the lowest value, 1 for the
+                             highest value).
+                     

+                         

+                             <Reference computation here>
+                     

+                         

+                             This is just to formally show where Cartool computes the reference, so
+                             just after the filters above. The next filters will use the optionally
+                             re-referenced data.
+                     

+                         

+                             Rectification:
+                     

+                         

+                             Making the data all positive.
+                         

+                             Usually a step before the Envelop filter below, but it can also be
+                             interesting sometimes to force the data to absolute.
+                     

+                         

+                             Absolute value
+                     

+                         

+                             Absolute of input value.
+                     

+                         

+                             Squared value (Power)
+                     

+                         

+                             Squared of input value, therfor equivalent to a power. Of course, results
+                             are positive...
+                     

+                         

+                             + Envelope, of window duration:
+                     

+                         

+                             Compute the Envelope, a kind of fast frequency analysis.
+                         

+                             To be able to compute the Envelope, all these points must be fulfilled:
    
+                                 
  • High- and Low-pass filters should be set
    • 
+                                 
  • Some Rectification (button above) should be set
    • 
+                                 
  • 
+                                     A sliding-window duration must be specified.
    The suggested
+                                     window size is  1.5 / LowFreq
+                                 
    • 
+                             

+                     

+                         

+                             Thresholding, keeping Above:
+                     

+                         

+                             Cutting the data at the specified threshold, 
+                                 keeping the values
+                                 above
+                             .
+                     

+                         

+                             Thresholding, keeping Below:
+                     

+                         

+                             Cutting the data at the specified threshold, 
+                                 keeping the values
+                                 below
+                             .
+                         

+                         

+                             Both Above and Below options can be used at the same time.
+                             In that case remaining values are both above and below
+                             the specified thresholds (interval).
+                     

+                         

+                             Options
+                     

+                         

+                              
+                     

+                         

+                             Sampling Frequency (set if missing):
+                     

+                         

+                             If the current file has a sampling frequency, its value will be shown here.
+                         

+                         

+                             If not, the field is editable, and it is mandatory to have a value
+                             entered to be able to apply any of the filters.
+                     

+                         

+                             Also apply filters to:
+                         

+                         

+                             Auxiliaries Channels
+                     

+                         

+                             Specifies if the auxiliary electrodes are to be filtered.
+                     

+                         

+                             Switch On / Off all filters set
+                     

+                         

+                             You can turn on and off all the currently entered filters. This is
+                             very convenient to see the effects of a set of filters, by simply
+                             turning the filtering on and off.
+                     

+                         

+                             OK
+                     

+                         

+                             Accept the filters.
+                         

+                         

+                             This button remains 
+                                 disabled until all the parameter
+                                 dialogs have received enough (and consistent) informations
+                             . If
+                             this is not the case, first check the current dialog: if its
+                             "Next" button is disabled, the problem is in the current
+                             dialog. Otherwise, browse the other dialogs for some missing informations.
+                     

+                         

+                             Cancel
+                     

+                         

+                             Quit the dialog, and remain in the previous filtering state.
+                     

+                         

+                             Help
+                     

+                         

+                             Launch the Help to the right page (should be here...).
+                     

+         

+         

+              
+         

+         

+             Filters combination and sequence
+         

+         

+             
+                 Filters are applied sequentially, following the top-down design of
+                 the dialog
+             . This means DC filter is first to be applied, then the
+             Butterworth, then the Spatial Filter and so on and so forth. Most of these
+             filters are not linearly permutables, which means the actual sequence 
+                 does matter a lot
+              on your results! The current sequence is the results
+             of 25+ years of experience in the field.
+         

+         

+              
+         

+         

+             When applying 
+                 both the Butterworth High Pass and the
+                 Butterworth Low Pass filters
+             , they will be automatically merged into
+             a single Butterworth Bandpass filter (instead of running
+             these two filters sequentially):
+         

+         
    
+             
  • 
+                 Order of the Bandpass will be the 
+                     sum of
+                     orders from the 2 single Butterworth filters
+                 .
    F.ex. if High
+                 and Low passes have each an order of 4, then the
+                 resulting Bandpass will have order of 2x4=8.
    This
+                 makes the final Bandpass filter orders to be multiples of 4.
+             
    • 
+             
  • 
+                 Bandpass will therefore be two times more powerful than the single
+                 filters alone, due to the doubling of order.
+             
    • 
+         

+         

+              
+         

+         

+             Filtering only affects the display in real-time
+                 , and does not
+                 alter the original data
+             . To permanently change the
+             data, you can either call File | Save As,
+             or go through the more versatile 
+                 
+                     Export
+                     Tracks
+                 
+              toolbox.
+         

+         

+             Filter causality
+         

+         

+             Sometimes, one needs to control how the filters make use of "data from the
+             future", so to speak.
+         

+         

+             A filter that receives data only from the past and present is said to be
+             causal, and non-causal if it makes use of data from the future. The latter
+             case can only happen once the recording has been done. It is done by applying
+             the filter once forward, then again once backward.
+         

+         

+              
+         

+         

+             Non-causal filter
+         

+         

+             The enormous advantage of the non-causal filtering for EEG analysis is that
+             it restores the phases of the original signal. This means
+             peaks' locations remain stable. It also restores the phases
+             for all frequencies, so the reconstructed signal also corresponds to the
+             original one, minus the removed frequencies of course. It is the default
+             option, and is widely used in the EEG community.
+         

+         

+             Note: when applying twice a filter, the decay at
+             cut-off frequency will no longer be -3dB (filter has been applied twice!).
+             Cartool counteracts this effect internally by operating a slight adjustment
+             to the cut-off frequency, so that the double-filtering has an actual -3dB
+             decay at cut-off.
+         

+         

+              
+         

+         

+             Causal filter
+         

+         

+             This can be used if one wants to make sure no data from the future might
+             have back-propagated and caused possible interference with the results.
+             This option is to be used mainly for picky reviewers... Note that all
+             real-time implementations like a recording machine must use a causal
+             filter - if any.
+         

+         

+             One big disadvantage a causal filter is the 
+                 delay added to the
+                 resulted filtered signal
+             . Peaks locations are no longer at the
+             right time positions! An aggravated issue is that the phase shifts differ
+             at each frequency, slightly "scrambling" the data.
+         

+         

+             Pamphlet you can include for publications
+         

+         

+             Here is the technical pamphlet for a single Butterworth filter,
+             replacing <actualorder> by the order used in the dialog:
+         

+         

+             The Butterworth Low / High pass filters are 
+                 <actualorder>
+              order filters, with <-20 x actualorder> dB/decade roll-off
+             and maximally flat response. They are implemented as cascaded 2nd
+             order sections with bilinear transform, and applied twice with one forward
+             and one backward pass to eliminate the phase shift.
+         

+         

+             When 
+                 
+                     both High Pass and Low Pass
+                     filters are applied
+                 
+             , it ends up with a 
+                 Butterworth
+                 Bandpass
+              - note the doubling order from the dialog numbers:
+         

+         

+             The Butterworth Bandpass filter is a <2 x actualorder>
+             order filter, with <-40 x actualorder> dB/decade roll-off and
+             maximally flat response. It is implemented as cascaded 2nd order
+             sections with bilinear transform, and applied twice with one forward and one
+             backward pass to eliminate the phase shift.
+         

+         

+             The Notch filter is implemented as a Butterworth Bandstop
+             filter - note the optional part if you selected All Harmonics:
+         

+         

+             The Notch filter is implemented as a Butterworth Bandstop filter
+             of order 12, with -240 dB/decade roll-off and maximally flat response, and a
+             stopband of 1Hz. It is implemented as cascaded 2nd order sections
+             with bilinear transform, and applied twice with one forward and one backward
+             pass to eliminate the phase shift. <optional part> Harmonic
+             frequencies have also been filtered out with cascaded Notch filters, up to
+             the Nyquist limit.
+         

+         

+             Note that if you are going to comment on all these filters in the same
+             section, you can shorten these pamphlet to avoid repeating the implementation
+             details that are exactly identical.
+         

+         

+              
+         

+         

+             Reference
+         

+         
Reference used for the implementation of the Butterworth filters:

+         
"Recursive Digital Filters - A Concise Guide",
 S. Hollos, J.R. Hollos,
 Abrazol Publishing, 2014, Exstrom Laboratories

-  

-   Time and frequency constraints

-  

-   Filters frequencies have some intrinsic limits (Nyquist and all these 
-   sorts of things), that Cartool will gracefully check for you when 
-   specifying new values. These limits depends on the sampling frequency 
-   (see below) AND the filter window (the number of time frames given to 
-   the filter function):

-  
    
-   
  • 
-   
    
-    Cartool will silently expand your requested time interval, 
-	compute the filters, then crop out the extra margin.
    
-	  
  • 
-      
    
-      The additional time margin is the maximum of:
    
-	  
      
-		  
    • 
-		  
      For High-pass filter, half the biggest possible 
-		  period, that is  order / ( high pass 
-		  cut-off * 2 )
      
-		  
    • 
-		  
      For Low-pass filter, the shortest possible 
-		  period, that is        
-		  order / ( low pass cut-off )
      
-		  
    • 
-		  
      For Band-pass or Band-stop, the 
-		  max of the first two above
      
-		  
    • 
-		  
      For Notch filter, a multiple of the period of the 
-		  fundamental  
-		  ( 6 * 12 ) / notch cut-off
      
-		  
    • 
-		  
      For Envelope filter,                                                           
-		  2 * Envelope width
      
-	  
    
-	  
  • 
-      
    
-      Some filters don't need any extra margin, being instantaneous 
-	  like the Ranking, Spatial, Rectification, 
-	  Thresholding filters etc...
    
-	  
  • 
-      
    
-      At the beginning and ending borders of the tracks, a mirroring 
-	  technique is used to fill the needed time points.
    
-   
  • 
-   
    
-    Filter parameters are then checked against this expanded time interval.
-     The actual frequency limits will therefore vary according to the 
-    window size / horizontal scaling.
    
-   
  • 
-   
    
-    If the current display window size changes, the 
-    frequencies of the filters will be temporarily clipped within the 
-    new limits. Though, the user-specified values are not lost, and 
-    restoring a bigger window will disable the clipping and the original 
-    values be used. This always brings the user on the safe side of the 
-    filters, at the expanse of changing the filter values.
    
-   

-  

-   Spatial Filter

-  

-   We developped a very specific spatial filter to improve the SNR of 
-   the data, a step which greatly improve the
-   segmentation and the
-   computation of inverse solution results:

-  
    
-	  
  • 
-	  
    This is an instantaneous filter, it 
-	  only makes use of the electrode values at a given time point
    
-	  
    • 
-	  
  • 
-	  
    It works partly as a non-linear statistical 
-	  filter by removing outliers
    
-	  
    • 
-	  
  • 
-	  
    And it also works partly as a linear 
-	  smoothing filter, the weights coming from the electrodes spatial 
-	  distribution
    
-	  
    • 
-  

-  

-    

-  

-   Method description

-  

-   For any given time point:

-  
    
-	  
  • Repeating for each electrode:
      
-		  
    • The values of the 6 closest neighbors are 
-		  determined, plus the central electrode value itself.
      • 
-		  
    • These 7 data points are then sorted.
      • 
-		  
    • The minimal and maximal values are removed by 
-		  dropping the first and last items of this list.
      • 
-		  
    • The new electrode value is the weighted average of the 5 
-		  remaining values, with weights being proportional to the
-		  inverse distance to the central electrode. The 
-		  central electrode is given a weight of 1.
      
-		  
      • 
-	  
    
-	  
    • 
-  

-  

-    

-  

-   Here is a visual example of the 6 closest Delaunay neighbors, with the 2 
-   extrema values removed (left), then the resulting smoothing (right):

-  

-   

-  

-    

-  

-   Technical points

-  
    
-	  
  • 
-	  
    The spatial filter is very similar to an Inter Quartile 
-	  Mean (IQM), but in our case cutting the Cumulated Density Function into 7 
-	  intervals instead of 4. We can therefor call it an Inter Septile 
-	  Weighted Mean.
    
-	  
    • 
-	  
  • 
-	  
    The spatial filter is reference independent. 
-	  It doesn't care if the reference is computed before or after the filter. 
-	  Indeed, any additive constant will change neither the ordering nor the 
-	  weighted sum (apart from the constant shift itself, of course).
    
-	  
    • 
-	  
  • 
-	  
    The spatial filter produces reliable average maps, 
-	  which is not the case with other formulas, like the regular Inter Quartile 
-	  Mean. This is very important for 
-	  computing template maps from the segmentation.
    
-	  
    • 
-	  
  • 
-	  
    The weights are derived from the 2D Delaunay 
-	  triangulation computed between the electrodes positions. Note 
-	  that in order to be scale-free, the distances are normalized so that the average distance 
-	  between the closest neighbors is equal to 1.
    
-	  
    • 
-  

-  

-    

-  

-    

-  

-   Finally, we can see here an example of before (A) and 
-   after (B) the Spatial filter, on the tracks (left) then on the maps (middle and right): 

-  

-   spatial filter

-  

-    

-  

-   Reference

-  
This is the published reference about the Spatial Filter:

-  
"EEG Source Imaging: A Practical Review of the Analysis Steps",
+         

+             Time and frequency constraints
+         

+         

+             Filters frequencies have some intrinsic limits (Nyquist and all these
+             sorts of things), that Cartool will gracefully check for you when
+             specifying new values. These limits depends on the sampling frequency
+             (see below) AND the filter window (the number of time frames given to
+             the filter function):
+         

+         
    
+             
  • 
+                 
    
+                     Cartool will silently expand your requested time interval,
+                     compute the filters, then crop out the extra margin.
+                 
    
+             
  • 
+                 
    
+                     The additional time margin is the maximum of:
+                 
    
+                 
      
+                     
    • 
+                         
      
+                             For High-pass filter, half the biggest possible
+                             period, that is  
+                                 order / ( high pass
+                                 cut-off * 2 )
+                             
+                         
      
+                     
    • 
+                         
      
+                             For Low-pass filter, the shortest possible
+                             period, that is        
+                                 order / ( low pass cut-off )
+                             
+                         
      
+                     
    • 
+                         
      
+                             For Band-pass or Band-stop, the
+                             max of the first two above
+                         
      
+                     
    • 
+                         
      
+                             For Notch filter, a multiple of the period of the
+                             fundamental  
+                                 ( 6 * 12 ) / notch cut-off
+                             
+                         
      
+                     
    • 
+                         
      
+                             For Envelope filter,                                                           
+                             2 * Envelope width
+                         
      
+                 
    
+             
  • 
+                 
    
+                     Some filters don't need any extra margin, being instantaneous
+                     like the Ranking, Spatial, Rectification,
+                     Thresholding filters etc...
+                 
    
+             
  • 
+                 
    
+                     At the beginning and ending borders of the tracks, a mirroring
+                     technique is used to fill the needed time points.
+                 
    
+             
  • 
+                 
    
+                     Filter parameters are then checked against this expanded time interval.
+                     The actual frequency limits will therefore vary according to the
+                     window size / horizontal scaling.
+                 
    
+             
  • 
+                 
    
+                     If the current display window size changes, the
+                     frequencies of the filters will be temporarily 
+                         clipped within the
+                         new limits
+                     . Though, the user-specified values are not lost, and
+                     restoring a bigger window will disable the clipping and the original
+                     values be used. This always brings the user on the safe side of the
+                     filters, at the expanse of changing the filter values.
+                 
    
+         

+         

+             Spatial Filter
+         

+         

+             We developped a very specific spatial filter to 
+                 improve the SNR of
+                 the data
+             , a step which greatly improve the
+             segmentation and the
+             computation of inverse solution results:
+         

+         
    
+             
  • 
+                 
    
+                     This is an instantaneous filter, it
+                     only makes use of the electrode values at a given time point
+                 
    
+             
    • 
+             
  • 
+                 
    
+                     It works partly as a 
+                         non-linear statistical
+                         filter by removing outliers
+                     
+                 
    
+             
    • 
+             
  • 
+                 
    
+                     And it also works partly as a 
+                         linear
+                         smoothing filter
+                     , the weights coming from the electrodes spatial
+                     distribution
+                 
    
+             
    • 
+         

+         

+              
+         

+         

+             Method description
+         

+         

+             For any given time point:
+         

+         
    
+             
  • 
+                 Repeating for each electrode:
      
+                     
    • 
+                         The values of the 6 closest neighbors are
+                         determined, plus the central electrode value itself.
+                     
      • 
+                     
    • These 7 data points are then sorted.
      • 
+                     
    • 
+                         The minimal and maximal values are removed by
+                         dropping the first and last items of this list.
+                     
      • 
+                     
    • 
+                         The new electrode value is the 
+                             weighted average of the 5
+                             remaining values
+                         , with weights being proportional to the
+                         inverse distance to the central electrode. The
+                         central electrode is given a weight of 1.
      
+                         
+                     
      • 
+                 
    
+             
    • 
+         

+         

+              
+         

+         

+             Here is a visual example of the 6 closest Delaunay neighbors, with the 2
+             extrema values removed (left), then the resulting smoothing (right):
+         

+         

+             
+         

+         

+              
+         

+         

+             Technical points
+         

+         
    
+             
  • 
+                 
    
+                     The spatial filter is very similar to an Inter Quartile
+                     Mean (IQM), but in our case cutting the Cumulated Density Function into 7
+                     intervals instead of 4. We can therefor call it an 
+                         Inter Septile
+                         Weighted Mean
+                     .
+                 
    
+             
    • 
+             
  • 
+                 
    
+                     The spatial filter is reference independent.
+                     It doesn't care if the reference is computed before or after the filter.
+                     Indeed, any additive constant will change neither the ordering nor the
+                     weighted sum (apart from the constant shift itself, of course).
+                 
    
+             
    • 
+             
  • 
+                 
    
+                     The spatial filter produces reliable average maps,
+                     which is not the case with other formulas, like the regular Inter Quartile
+                     Mean. This is very important for 
+                         computing template maps from the segmentation
+                     .
+                 
    
+             
    • 
+             
  • 
+                 
    
+                     The 
+                         weights are derived from the 2D Delaunay
+                         triangulation
+                      computed between the electrodes positions. Note
+                     that in order to be scale-free, the distances are normalized so that the average distance
+                     between the closest neighbors is equal to 1.
+                 
    
+             
    • 
+         

+         

+              
+         

+         

+              
+         

+         

+             Finally, we can see here an example of before (A) and
+             after (B) the Spatial filter, on the tracks (left) then on the maps (middle and right): 
+         

+         

+             spatial filter
+         

+         

+              
+         

+         

+             Reference
+         

+         
This is the published reference about the Spatial Filter:

+         
"EEG Source Imaging: A Practical Review of the Analysis Steps",
 C.M. Michel, D. Brunet,
 Front. Neurol., 04 April 2019

-  

-   Average Reference  

-  

-   Toggles on or off the Average Reference.
-    This is equivalent to setting the average
-    reference through the Menu.

-  

-   Brightness  

-  

-   Only when in the Intensity mode can 
-   you adjust the brightness / intensity of the colors.

-  

-   This is equivalent to changing the value assigned to the maximum color.

-  

-   See an example here, with the MRI
-    display.

-  

-   Contrast  

-  

-   Contrast does not change the maximum value mapped to the maximum 
-   color, but changes the slope of the mapping, increasing or 
-   decreasing the color differences between low and high values.

-  

-   See an example here, with the MRI
-    display.

-  

-   Color auto scaling  

-  

-   Sets the maximum volume value to the maximum color value. Put it 
-   another way: automatically sets the brightness to match and correctly 
-   display the data. Consequently, the brightness 
-   buttons become inactive, but still the contrast 
-   can be adjusted.

-  

-   Color modes  

-  

-   Cycles through different color tables (black to white, white to 
-   black, black to yellow to white, etc...).

-  

-   EEG - Mouse

-  

-   Go here for the mouse actions 
-   common to all views.

-  

-   Chart of all mouse operations for EEG

-  

-   
-    
-     
-     
-     
-     
-     
-    
-    
-     
-     
-     
-     
-     
-    
-    
-     
-     
-     
-     
-     
-    
-    
-     
-     
-     
-     
-     
-    
-    
-     
-     
-     
-     
-     
-    
-   

-      

-       Alternate key

-      

-       

-        Mouse button

-      

-       

-        None

-      

-       

-        Shift

-      

-       

-        Control

-      

-       

-        Control+Shift

-      

-       

-        Left

-      

-       

-        time selection

-        or

-        rotation if in
-         3D

-      

-       

-         

-      

-       

-        same as Middle

-        or

-        zoom if in
-         3D

-      

-       

-        same as Shift Middle

-      

-       

-        Middle

-      

-       

-        tracks selection

-      

-       

-        bad tracks selection

-      

-       

-         

-      

-       

-         

-      

-       

-        Right

-      

-       

-        horizontal scrolling

-        or

-        next/previous tracks

-      

-       

-        horizontal zoom

-        or

-        vertical zoom

-      

-       

-         

-      

-       

-        baseline offset shifting 

-      

-       

-        Double Left

-      

-       

-        keep only sub-window

-      

-       

-         

-      

-       

-         

-      

-       

-         

-  

-    

-  

-   Time selection: left click

-  

-   Click (and extend) the left button to set the current 
-   time point/time range:

-  

-   

-  

-   If you hold down the left button, you can extend
-    the cursor to any size you want, even outside the current 
-   window. In this case, the window will scroll while you move the 
-   cursor outside the window:

-  

-   

-  

-   See also the keyboard way of moving 
-   the cursor.

-  

-   Tracks selection: middle click

-  

-   Click (and extend vertically) the middle button to 
-   select/deselect some tracks.

-  

-   You can use Control + left click if you don't have a middle 
-   button. Also note that you have to click close to the baseline of the 
-   track, not on the track itself!

-  

-   The selected tracks are drawn in pink:

-  

-   

-  

-   To deselect some tracks, middle click again on them.

-  

-   To deselect all tracks, middle click somewhere far 
-   enough from the tracks, say, around the electrode names.

-  

-   For more controls and possible uses, see the menu Selection.

-  

-   The tracks selection does not interfere with the time 
-   selection at all.

-  

-   Bad tracks selection: Shift + middle click

-  

-   Use Shift and click the middle button to 
-   set/reset some bad tracks.

-  

-   The bad tracks are drawn in light red:

-  

-   

-  

-   Bad tracks (broken electrode, noisy signal etc...) are taken out of 
-   the calculus of the computed tracks, 
-   and the number of significant electrodes decreased by their amount. 
-   They are also independently rescaled, so that any high amplitudes 
-   will not visually degrade the display. You can easily show or remove 
-   them through the Selection menu.

-  

-   Horizontal scrolling or Next / 
-   Previous tracks: right click

-  

-   Click the right button, then drag either 
-   horizontally or vertically.

-  

-   If the initial direction of the mouse is horizontal, the 
-   window will be subsequently scrolled horizontally. Otherwise, 
-   the scrolling will be applied vertically, to the tracks,
-    by shifting to the next/down tracks 
-   or the previous/upper tracks. More 
-   intuitive if you try it!

-  

-    

-  

-   The visual hints 
-   associated, moving horizontally (time), or vertically (tracks):

-  

-   

-   

-  

-   Horizontal & vertical zoom: Shift + 
-   right click

-  

-   Use Shift and click the right button, then drag
-    either horizontally or vertically.

-  

-   The direction you choose will select which dimension will be zoomed 
-   in/out: horizontal or vertical.

-  

-   When zooming horizontally, Cartool will center the current view 
-   to the current cursor position, which can be handy to quickly 
-   recenter your view to a given time frame.

-  

-   See also the next point below to some some tracks specifically.

-  

-    

-  

-   The visual hints 
-   associated, for the vertical and horizontal zoom:

-  

-   

-   

-  

-   Relative vertical zoom: Control + 
-   Shift + right click

-  

-   Use Control + Shift and click the right button,
-    then drag either horizontally or vertically.

-  

-   This will zoom in/out only the currently
-    selected tracks, using the same procedure as the global
-    scaling.

-  

-   If no tracks are selected, then the global scaling applies. The 
-   procedure can be repeated as many time, and on any tracks subset, as needed.

-  

-   To reset the scaling to the global default, use the  Options
-    | Reset tracks scaling  menu.

-  

-    

-  

-   This is a way you can emphasize (interesting but too small) or 
-   de-emphasize (noisy and big) some particular tracks by giving them a local
-    scaling of their own:

-  
    
-   
  • 
-   
    
-    a regular, uniform scaling:
    
-   

-  

-   

-  
    
-   
  • 
-   
    
-    some specific scaling:
    
-   

-  

-   

-  

-   Finally, note that the rescaling buttons 
-   will only work globally, even though some tracks might be selected.

-  

-   Baseline offset shifting: Control + 
-   right click

-  

-   Use Control and click the right button, then drag
-    vertically.

-  

-   This will move the whole tracks baseline (axis) up and down. If the 
-   data are highly skewed toward an extreme value, this allows the 
-   re-center the display around that limit, and then play with the 
-   vertical zooming as usual.

-  

-   To manually set a baseline value, or to reset it to its default (i.e. 
-   0), see the  Options
-    | Reset baseline offset  menu.

-  

-    

-  

-   See here the default baseline, and a shifted baseline of -150:

-  

-      
-    

-  

-    

-  

-   The visual hints 
-   associated when shifting the baseline:

-  

-   

-  

-   Keep only one sub-window: double left click

-  

-   When the EEG tracks are rendered into 
-   different sub-windows, double left clicking one of these will 
-   switch the display to that single sub-window alone.

-  

-   Drag & Drop

-  

-   You can Drag & Drop any .mrk 
-   file into the window, and all markers from that file fitting the 
-   current EEG time range will be added to the current list.

-  

-   EEG - Keyboard

-  

-   Go here and here 
-   for the keyboard actions common to all views.

-  

-   Moving cursor

-  

-   With left and right arrows, you move accordingly the time
-    cursor. Another way is to use the mouse.
-    However, using the keyboard is more accurate, and while holding down 
-   the key, Cartool will slowly accelerates. When the cursor 
-   leaves the last visible time frame, Cartool will scroll the display 
-   of an appropriate amount. Altogether with the acceleration, you can 
-   easily browse to even huge files very efficiently.

-  

-   To prevent the automatic acceleration, press Control + left 
-   or Control + right arrows, so you can go through all time frames.

-  

-   An extended cursor is moved the same way, though it may appear to 
-   behave strangely sometimes. In case the cursor is actually wider than 
-   the number of time frames currently displayed, moving the cursor 
-   forward will show only the end of the cursor. And moving the cursor 
-   backward will show only the beginning of the cursor.

-  

-   Next or previous page

-  

-   Use the page down and page up to jump to the next or 
-   previous screen respectively. The amount of time frames jumped over 
-   is exactly the number of time frames currently displayed. These keys 
-   will also slowly accelerate when held down.

-   The cursor will also jump accordingly, that is, it will remain stable 
-   within the window.

-  

-   Beginning or end of Eeg

-  

-   Pressing the home key will of course scroll the display 
-   to time frame 0, and set the cursor to 0. Conversely, pressing 
-   the end key will do the same with the last time frame. The 
-   number of time frames displayed is not altered.

-  

-   Quickly creating markers

-  

-   Pressing Control + Numpad 1 to 9 to set the any of the 
-   9 possible quick markers:

-  
    
-   
  • 
-   
    
-    On first call, Cartool will ask the associated marker name 
-    for that keystroke combination
    
-   
  • 
-   
    
-    On later calls, Cartool will create a marker at current 
-    cursor position, using the marker name entered on first 
-    call 
    
-   

-  

-   Quickly jumping the cursor by blocks

-  

-   Pressing Control + Left or Right arrow to move the 
-   cursor backward or forward, of the amount of its current size.

-  

-   F.ex. if the cursor is currently extending from time frame 0 to 99, 
-   pressing Control + Right will make the cursor jump to 100 to 199, 
-   then 200 to 299 and so on. Combine this with quickly creating
-    markers, then you have a winner combo to quickly browse a file 
-   and tag blocks of data.

-  

-   EEG - Menus

-  

-   Edit menu

-  
    
-   
    
-    Copy as Text
    
-   
      
-    
      
-     Copy to the clipboard the current selected
-      tracks, and for the current selected
-      time, in a text format. If no tracks are specially selected, 
-     then all tracks are taken. The output format is: a row holds all 
-     electrodes of 1 time frame, and the number of rows is the number of time
-      frames. Values are tab separated, with new line at 
-     the end of each row, so you can properly paste both in a text editor 
-     and Excel.
      
-    
    
-   
    
-    Copy as Bitmap
    
-   
      
-    
      
-     Do a snapshot in the clipboard, see here.
      
-    
    
-   
    
-    Export Tracks
    
-   
-   

-  

-   Selection menu

-  

-   This (extensive) menu is about tracks selection and categorization.

-  

-   Please note that only the non-trivial functions will be commented, 
-   otherwise each command is considered self-explanatory!

-  

-   Main list

-  
    
-   
    
-    Keep current selection
    
-   
      
-    
      
-     ..on display
      
-    
    
-   
    
-    Exclude current selection
    
-   
      
-    
      
-     ..from display
      
-    
    
-   
    
-    Clear selection
    
-   
    
-    Select all tracks
    
-   
    
-    Select all visible tracks
    
-   
    
-    Invert selection
    
-   
    
-    Select tracks above threshold
    
-   
      
-    
      
-     Tracks that are in absolute value above a user-specified threshold.
      
-    
    
-   
    
-    Select tracks from a list
    
-   
      
-    
      
-     The user provides a list of tracks name to select from
      
-    
    
-   

-  

-   Bad tracks

-  
    
-   
    
-    Set current selection as Bad tracks
    
-   
      
-    
      
-     Flags the selected tracks as bads, which removes them from some 
-     computation, like GFP, Disssimilarity and Average.
      
-    
    
-   
    
-    Restore all bad tracks to Normal
    
-   
    
-    Restore only the selected bad tracks
    
-   
    
-    Keep only the current bad tracks
    
-   
    
-    Exclude the current bad tracks
    
-   
    
-    Select current bad tracks
    
-   
      
-    
      
-     ..from either the current selection, if any, or from the current 
-     displayed tracks otherwise.
      
-    
    
-   
    
-    Deselect current bad tracks
    
-   
      
-    
      
-     ..from either the current selection, if any, or from the current 
-     displayed tracks otherwise.
      
-    
    
-   
    
-    Select current non-bad tracks
    
-   
      
-    
      
-     ..from either the current selection, if any, or from the current 
-     displayed tracks otherwise.
      
-    
    
-   
    
-    Select current non-bad / non-aux tracks
    
-   
      
-    
      
-     ..from either the current selection, if any, or from the current 
-     displayed tracks otherwise.
      
-    
    
-   

-  

-   Auxiliary tracks

-  
    
-   
    
-    Set current selection as Auxiliary tracks
    
-   
      
-    
      
-     Flags the selected tracks as auxiliaries, like ECG, EOG etc...
      
-    
      
-     Usually, Cartool will ask you if you want to remember your new 
-     auxiliaries configuration as the default (for your current type of 
-     file only). If yes, any future opening of that type of file will use 
-     your configuration. If no, your configuration will only apply to the 
-     lifetime of your current opened file.
      
-    
    
-   
    
-    Restore all auxiliary tracks to Normal
    
-   
      
-    
      
-     Same remark as above.
      
-    
    
-   
    
-    Restore only the selected auxiliary tracks
    
-   
      
-    
      
-     Same remark as above.
      
-    
    
-   
    
-    Restore auxiliaray tracks to default
    
-   
      
-    
      
-     Reset the auxiliary configuration to its default (for your current 
-     type of file only), forgetting any override you may have done before.
      
-    
    
-   
    
-    Keep only the current auxiliary tracks
    
-   
    
-    Exclude the current auxiliary tracks
    
-   
    
-    Select current auxiliary tracks
    
-   
      
-    
      
-     ..from either the current selection, if any, or from the current 
-     displayed tracks otherwise.
      
-    
    
-   
    
-    Deselect current auxiliary tracks
    
-   
      
-    
      
-     ..from either the current selection, if any, or from the current 
-     displayed tracks otherwise.
      
-    
    
-   
    
-    Select current non-auxiliary tracks
    
-   
      
-    
      
-     ..from either the current selection, if any, or from the current 
-     displayed tracks otherwise.
      
-    
    
-   
    
-    Select current non-bad / non-aux tracks
    
-   
      
-    
      
-     ..from either the current selection, if any, or from the current 
-     displayed tracks otherwise.
      
-    
    
-   

-  

-   Tracks analysis

-  

-   (note that these are currently experimental functions, but you 
-   risk nothing by trying/using them!)

-  
    
-   
    
-    Search Flat tracks
    
-   
      
-    
      
-     Select tracks with constant values, which usually were not recorded. 
-     Note that the reference track should be kept and is/should not be 
-     selected by this method:
      
-    
      
-     
      
-    
    
-   
    
-    Search Broken / jerky tracks
    
-   
      
-    
      
-     Select highly saturated, or very random tracks, which clearly haven't 
-     recorded anything EEG-like:
      
-    
      
-     
      
-    
    
-   
    
-    Search Outlier / noisy tracks
    
-   
      
-    
      
-     Select tracks that do look like EEG, but of very low 
-     informational quality. These tracks stand out from the others, even 
-     after filtering, and therefor greatly degrade the GFP (or Standard Deviation):
      
-    
      
-     
      
-    
    
-   
    
-    Search Altogether: Flat + Broken + Outlier tracks
    
-   
      
-    
      
-     Use all three criterion above to search for globally artefacted 
-     tracks. First image shows the selection, second image shows the 
-     selection flagged as bad tracks, clearing up the display:
      
-    
      
-     
      
-    
    
-   

-  

-   Remarks on the tracks analysis:

-  
    
-   
  • 
-   
    
-    The analysis goes through a lot of statistics computed on 
-    all electrodes and on the whole time range (minus the 
-    first and last 10%, and sometimes minus the eye blinks epochs). The 
-    results are tracks that are globally bad all over the recording,
-     not at some specific epochs like eye blinks.
    
-   
  • 
-   
    
-    The analysis uses your current filters, because this is what 
-    will matter for your processing at hand. Changing the filters will 
-    likely change the results of the analysis, like a high-pass that can 
-    help recover a drifting track, or a Notch with line interference. It 
-    shouldn't be dramatically different, though.
    
-   
  • 
-   
    
-    The analysis is done with the recording reference, 
-    re-referencing is not used.
    
-   
  • 
-   
    
-    The 3 processing run in increasing complexities, so in case of 
-    doubts, run them sequentially from the first one to the last one.
    
-   
  • 
-   
    
-    Bear in mind that the result is just a track selection, and 
-    that no action has been really taken. It is up to you to just ignore 
-    the result, or to manually include / exclude some other tracks, and 
-    to actually flag the selection as bad tracks.
    
-   
  • 
-   
    
-    The analysis is primarily targetting EEG recordings, because 
-    it contains all the original noise and artefacts. You can run it on 
-    ERPs, though, but the averaging process might have hidden some of the artefacts.
    
-   

-  

-   Markers menu

-  

-   Don't remember what is a marker, a trigger 
-   or an event? or the .mrk 
-   marker file format?

-  

-    

-  
    
-   
    
-    Add marker at current cursor position
    
-   
-   
    
-    Delete markers within cursor range
    
-   
      
-    
      
-     Deletes only the markers that are entirely included within the 
-     current cursor position. Be careful, no undo is possible.
      
-    
    
-   
    
-    Delete markers by names
    
-   
      
-    
      
-     Deletes only the markers that match a given string
-      expression. Be careful, no undo is possible.
      
-    
    
-   
    
-    Delete all markers
    
-   
      
-    
      
-     Delete all markers, for the whole file. Be careful, no undo is possible.
      
-    
    
-   
    
-    Search for marker
    
-   
-   
    
-    Next hit
    
-   
-   
    
-    Previous hit
    
-   
-   
    
-    Rename markers within cursor range
    
-   
      
-    
      
-     Force renaming all markers within the current cursor range.
      
-    
    
-   
    
-    Rename all markers
    
-   
      
-    
      
-     Specify a substring to be replaced (any type of characters), and a 
-     replacement substring. It will run through all occurences within a 
-     marker name, replacing the old string by the new one, and for all 
-     markers. If the replacement string is empty, this will delete the 
-     searched string.
      
-    
      
-     Applications are numerous, as replacing spaces by "_", or 
-     the other way round, changing esoteric codes (173) into meaningful 
-     messages ("Elephant sound"), merging different codes into a 
-     single one, and so on.
      
-    
    
-   
    
-    Merge exact overlapping markers
    
-   
      
-    
      
-     All markers that perfectly overlap (same starting points and 
-     same ending point) will be merged together, also merging their names.
      
-    
    
-   
    
-    Merge identical contiguous markers
    
-   
      
-    
      
-     Merge markers with the exact same name and that are contiguous in 
-     time. This can be useful if you have labelled blocks of data that you 
-     want to re-group into bigger blocks.
      
-    
    
-   
    
-    Scanning tracks to generate markers
    
-   
-   
    
-    Duplicate triggers into markers
    
-   
      
-    
      
-     Copies all triggers into markers,
-      which allows you to further process / edit them, which is not the 
-     case for the triggers.
      
-    
      
-     You also have to select the correct display,
-      if you want to see only the markers, as otherwise you will 
-     see both the triggers and the markers, which can be a little bit confusing.
      
-    
    
-   
    
-    Split bitwise triggers / markers names
    
-   
      
-    
      
-     This will scan the currently displayed triggers or markers, and will 
-     split them according to their names, creating new markers. The idea 
-     is to break each name into its binary components, f.ex.
      
-    
        
-     
      • 
-     
        
-      "24" will be splitted into markers "16" and "8";
        
-     
      • 
-     
        
-      "17" into "16" and "1";
        
-     
      • 
-     
        
-      "6" into "4" and "2";
        
-     
      • 
-     
        
-      "3" into "2" and "1".
        
-     
      
-    
      
-     To be more selective, a mask has to be specified before running the 
-     process. Only the bits set to 1 in the binary representation of that 
-     mask will be processed. F.ex. if the mask is 255 (1111 1111 in 
-     binary), we will have all the markers of the previous example. 
-     However, if the mask is 17 (0000 1001 in binary), the results would 
-     only be "16", "16" and "1", nothing, 
-     "1". In this way, you can restrict the generated markers.
      
-    
      
-     This process is applied only to the currently displayed type of 
-     triggers / markers. However, only markers are generated.
      
-    
      
-     The names have to be integer, you can not split triggers whose names 
-     would be "Eyes open" or "Abcd"!
      
-    
    
-   
    
-    Manage the list of marker names
    
-   
      
-    
      
-     Brings the list of currently known marker names. Then you can add 
-     a new name, modify existing names, or delete names.
      
-    
      
-     At least one name should remain in the list, though.
      
-    
    
-   
    
-    Import markers from file
    
-   
      
-    
      
-     Reads another .mrk file and copies its markers.
      
-    
    
-   
    
-    Switch to another marker file
    
-   
      
-    
      
-     (Advanced feature) This will switch the currently associated .mrk 
-     file (storing the markers), to another .mrk file. Any 
-     subsequent updates will then occur on this file.
      
-    
    
-   
    
-    Display
-    
      
-     None
-     
        
-      No triggers or markers of any sorts are displayed
        
-     
      
-    
      
-     Events
-     
        
-      Toggles on or off the display of events
        
-     
      
-    
      
-     Triggers
-     
        
-      Toggles on or off the display of triggers
        
-     
      
-    
      
-     Markers
-     
        
-      Toggles on or off the display of markers
        
-     
      
-    
      
-     All
-     
        
-      Shows all available events, triggers and markers
        
-     
      
-    
    
-   
    
-    Filtering display
    
-   
      
-    
      
-     Show only the triggers / markers that successfully match a string
-      expression.
      
-    
      
-     This is a very useful feature to show a restricted subset of markers, 
-     hiding all the others, and therefore increasing the display 
-     readability when too many markers coexist together.
      
-    
    
-   
    
-     
    
-   

-  

-   Notes on marker files

-  

-   When all markers have been deleted, the .mrk file 
-   associated to the Eeg file will be also deleted. Conversely, 
-   when the very first marker is created, the .mrk file is also created.

-  

-   For security reasons, any time you add or remove any single marker, 
-   the .mrk file is immediately updated on disk. This way, 
-   in case of any crash, your markers will be securely saved.

-  

-   Options menu

-  
    
-   
    
-    Reference
-    
      
-     As in file
-     
        
-      No subtraction occurs, the data are shown exactly as they are stored
-       in the Eeg file (then you should know which reference was used...)
        
-     
      
-    
      
-     Average
-     
        
-      After applying any filters, the mean value of the tracks is 
-      computed and subtracted to all tracks. This is repeated for 
-      all time frames idependently. See the formulas,
-       and the equivalent button.
        
-     
      
-    
      
-     Single track
-     
        
-      After applying any filters, the value of the specified 
-      track is subtracted to all tracks. This is repeated for all time 
-      frames idependently.
        
-     
      
-    
      
-     Multiple tracks
-     
        
-      After applying any filters, the average value of the specified
-       tracks is subtracted to all tracks. This is repeated for all 
-      time frames idependently.
        
-     
      
-    
      
-     Montage
-     
        
-      First requires a .mtg 
-      montage file. After applying any filters, and according to the 
-      montage specifications, any mix of differences between pairs of tracks 
-      or single tracks values are shown. This is repeated for all 
-      time frames independently. This affects only the display, not the 
-      data themselves, so you can not export the results.
        
-      Within one of these modes, the 
-      results are correctly positionned between the two subtracted 
-      electrodes, giving a visual cue of your montage.
        
-     
      
-    
    
-   
    
-    Time
-    
      
-     Show Date
-     
        
-      If the date information is available from the Eeg file, either choose 
-      to show it or not.
        
-     
      
-    
      
-     Show Time
-     
        
-      If the time information (in hours/minutes/seconds etc...) is 
-      available in the Eeg file, either choose to show it or not.
        
-     
      
-    
      
-     Absolute time, from the recording
-     
        
-      Choose to use the absolute time, the one when the recording has been 
-      done, f.ex. starting at 9h37m10s.
        
-      You can then relate some events in the EEG to the ones in 
-      "real" life, like seasures.
        
-     
      
-    
      
-     Relative time, origin at the beginning
-     
        
-      Set the time origin at the first Time Frame recorded, giving you a 
-      relative time starting at 0h0m0s.
        
-     
      
-    
      
-     Relative time, arbitrary origin
-     
        
-      Set the time origin to an arbitrary position in the file. By default, 
-      Cartool will propose the current position of the cursor, or you can 
-      give any value as a relative offset from the beginning of the file.
        
-      You can give a position that is not within the relative time range of 
-      the file, and even a negative value.
        
-      This is the feature used to automatically set the origin if a marker 
-      is found with the name "Origin". The origin is drawn with 
-      the little vertical bar on the time axis:
        
-      
        
-     
      
-    
      
-     Go to time origin
-     
        
-      Quickly move the Time Cursor to the time origin.
        
-     
      
-    
    
-   
    
-    Set Display Scaling
    
-   
      
-    
      
-     Ask the user (you actually...) to give the maximum amplitude to be 
-     shown in the current window. Works until you rescale the window.
      
-    
    
-   
    
-    Set Time Window
    
-   
      
-    
      
-     Give a time range for the current page. Default input is in 
-     milliseconds, but you can override it by adding "s" for 
-     seconds, f.ex.: 10s, 2.5s etc...
      
-    
    
-   
    
-    Reset Tracks Scaling
    
-   
      
-    
      
-     Some tracks might have user-defined relative
-      scalings, making them appear greater or smaller then their 
-     peers. This will reset these differential scalings. If no tracks are selected,
-      all tracks are reseted, otherwise only the selected ones will be.
      
-    
    
-   
    
-    Specify a Baseline Offset
    
-   
      
-    
      
-     Vertically shift the whole tracks of the specified amount, setting it 
-     as the new the baseline value.
      
-    
    
-   
    
-    Reset Baseline Offset
    
-   
      
-    
      
-     Reset to 0 the baseline offset.
      
-    
    
-   
    
-    Line Width
    
-   
      
-    
      
-     Specify a line width. Default is 0, which activates the Smart
-      Line Width features. This will choose the best line width 
-     according to the context:
      
-    
        
-     
      • 
-     
        
-      A high density of time points, and / or a high number of tracks 
-      will select the thinnest line width available.
        
-      
      • Less tracks, or less time points, or bigger window, 
-      or more zoom will little by little increase the line width.
        
-      
      • Superimpose mode will always select the thinnest 
-      line width.
        
-     
      
-    
      
-     If not 0, the width specified will be used as is. Valid values 
-     will depend on your graphic card, 
-     including fractional numbers, and 1 being the default.
      
-    
    
-   
    
-    Show/hide Baseline Axis
    
-   
      
-    
      
-     Nothing to add.
      
-    
    
-   
    
-    Goto Another Session / Block
    
-   
      
-    
      
-     If the Eeg file embeds multiple recordings, sometime known as 
-     sessions or blocks, you can shift to another one. See this button.
      
-    
    
-   
    
-    Easy publish
    
-   
      
-    
      
-     This feature is not yet implemented, but will be very soon. For sure, 
-     it will scan your data, analyse them, do all the tests, output the 
-     figures, and build an article ready to be accepted in the highest 
-     ranked publications. And everything done in 5 minutes while playing 
-     your favorite mp3 playlist.
      
-    
    
-   

-  

-   Scanning for Markers

-  

-   This is a versatile way to scan tracks for some propertie to 
-   generate some markers. The 
-   markers generated can either be used for display (i.e. where 
-   the interesting parts of the data are), or for later processing 
-   (like averaging).

-  

-   At the end of the chapter, there are a few examples,
-    if you get confused.

-  

-    

-  

-   Scanning methods

-  

-   There are four methods to scan tracks:

-  
    
-   
  • 
-   
    
-    Periods of Stability: used when tracks contain kind of on/off, 
-    plateau-like encoding (like hard-wired triggers).
    
-   
  • 
-   
    
-    Local Extrema: used to search for local minima and maxima of 
-    tracks (including the GFP).
    
-   
  • 
-   
    
-    Thresholds: used to detect when tracks go beyond or fall below 
-    a given threshold.
    
-   
  • 
-   
    
-    Template Matching: used to detect a spatio-temporal pattern on 
-    all tracks at once.
    
-   

-  

-    

-  

-   The markers resulting from the scan are added to the EEG's associated .mrk file,
-    which you can edit or re-process yourself for more advanced purposes.

-  

-   There is certainly a trial and error phase before you find the 
-   right parameters. It may be a good idea to first select a short time 
-   interval and/or only a few tracks before running the scan on the full 
-   file. Also don't forget to delete 
-   previous markers before re-doing a whole scan, otherwise they 
-   will simply cumulate!

-  

-   Scanning for Markers dialog

-  

-   

-    

-   

-  

-   
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-   

-      

-       What to Scan

-      

-        

-      

-       Tracks:

-      

-       These are the tracks to analyse.

-      

-       Each track is analysed independently of the others (except 
-       with Template Matching, which 
-       operates on maps, i.e. on all tracks at once).

-      

-       Selecting some tracks from the 
-       display before calling this dialog will pre-fill this field.

-      

-       Time Period:

-      

-       The time range to scan.

-      

-       These fields are pre-filled with the current
-        time selection, or the whole time range of the file.

-      

-       Scanning for

-      

-        

-      

-       Periods of Stability

-      

-       A track has to remain on a constant level for some time. The 
-       level itself does not matter (anything non-zero), the track has just 
-       to be constant.

-      

-       Local Extrema

-      

-       Finding local minima and/or maxima.

-      

-       Min

-      

-       Scan for local minimum.

-      

-       Use some low-pass filter to reduce the 
-       sensitivity / scale of this detection.

-      

-       See this note.

-      

-       Max

-      

-       Scan for local maximum.

-      

-       Use some low-pass filter to reduce the 
-       sensitivity / scale of this detection.

-      

-       See this note.

-      

-       Thresholds

-      

-       A track has to be above or below some threshold.

-      

-       Note that both above and below criterion can be selected 
-       simultaneously. In that case, you end up with an interval testing.

-      

-       Test if Above:

-      

-       The track has to be above the specifed value, positive or negative.

-      

-       Test if Below:

-      

-       The track has to be below the specifed value, positive or negative.

-      

-       Set marker position to:

-      

-        

-      

-       First TF past threshold

-      

-       The marker is strictly inserted at the first TF where 
-       the test is found positive.

-      

-       Highest slope around threshold

-      

-       The detected position will drift to wherever side which has the 
-       highest slope, and will stop there.

-      

-       The purpose of this option is to help align raising-edge events.

-      

-       Template Matching

-      

-       This has to be thought as trying to find a sequence of maps in 
-       the data. Tracks are not considered individually, but as a whole 
-       pattern (a map). Plus, the maps also evolve in time.

-      

-       See this note for more details about how template
-        matching is done here.

-      

-       Template file:

-      

-       The file with the template to serach for. It should have the same 
-       number of electrodes as the EEG file to scan.

-      

-       It can be any kind of EEG file format.

-      

-       Correlation above which to accept:

-      

-       Specifies the correlation value (in percentage) above which the test 
-       will be positive.

-      

-       Correlation does account for sign, that is, correlation -90 is 
-       below 50.

-      

-       Time Constraints

-      

-        

-      

-       Condition has to be true between ... and 
-       ... [TF]

-      

-       Constraint the test chosen by defining time limits.

-      

-       F.ex. we can be interested in short duration plateau, at least 3 TF 
-       longs, but shorter than 30 TF. In case you don't care, set a wide 
-       range, like from 1 to 10000!

-      

-       These fields don't apply to local extrema, which by definition are 
-       only 1 TF long.

-      

-       See this note to visualize how the time 
-       constraints work.

-      

-       Then condition has to be false for ... [TF]

-      

-       Set the minimum amount of time after the test fails before a new 
-       marker can start again. Should be at least 1.

-      

-       See this note to visualize how the time 
-       constraints work.

-      

-       Simultaneous markers:

-      

-       Each track can generate its own marker, so we can deal with this.

-      

-       These options are off when Scanning for 
-       a template.

-      

-       One Marker per Track

-      

-       Let each simultaneous marker remain that way.

-      

-       Use the Naming Markers options to 
-       help sort out who is who!

-      

-       Merged into Single Marker

-      

-       Post-process markers that lie in a given range, and merge them into a 
-       single one. See this note.

-      

-       Also see the Naming Markers  
-       to also merge the names.

-      

-       Tolerance [TF]

-      

-       Give a maximum time extent within which "simultaneous" is meant.

-      

-       Set to 0 to consider only perfectly aligned markers.

-      

-       Naming Markers

-      

-       You can tune the markers' name to your liking.

-      

-       Beginning with Prefix

-      

-       Optionally start all the markers with this prefix.

-      

-       By default, it reflects the kind of Scanning method 
-       you chose, like "Stab", "Thresh", etc...

-      

-       Including name

-      

-       Optionally include the track name.

-      

-       When Scanning for a template, this 
-       is replaced by the Template file name.

-      

-       Off when merging markers.

-      

-       Ending with value:

-      

-       The following options are quite context sensitive!

-      
    
-       
    
-        None

-      

-       What it says.

-      
    
-       
    
-        Track Value

-      

-       The value of the track that generates the marker at that position.

-      

-       Useful f.ex. to retrieve the Max value of a track. When Scanning
-        for a template, this is replaced with the Correlation value.

-      

-       Off when merging markers.

-      
    
-       
    
-        Relative Index

-      

-       Add an index corresponding to the relative position of the track 
-       generating the marker.

-      

-       Indexes are not 1, 2, 3, 4... but in powers of 2, like: 1,
-        2, 4, 8... So we can add these values when  merging
-        markers together: f.ex. tracks 3 and 4 together will produce a 
-       code of 4 + 8 = 12. If you don't see the use of this, well, 
-       just forget it!

-      

-       Off when Scanning for a template.

-      
    
-       
    
-        Merged Count

-      

-       When (and only when) merging markers,
-        add a count of how many markers were doomed to be merged.

-      

-       Off when Scanning for a template.

-      

-       Process

-      

-       Runs the scan.

-      

-       This button remains disabled until all the parameter 
-       dialogs have received enough (and consistent) informations.

-      

-       Cancel

-      

-       Quit the dialog.

-      

-       Help

-      

-       Launch the Help to the right page (should be here...).

-  

-    

-  

-   Scanning for markers - Technical points & hints

-  

-   Filtering & reference

-  

-   The scan is run on the tracks as they appear to you, that is with the 
-   current reference and filters.
-    Therefor changing these settings can dramatically affect the 
-   markers. This can actually be used for the best, for example when 
-   searching for local maxima.

-  

-   Stopping the scan

-  

-   Just press Escape to get out of a lengthy detection...

-  

-   Local Extrema

-  

-   The detection occurs at the reversal of the signs of 2 successive derivatives.

-   If there is a plateau on either side, this will make one of the 
-   derivative null, therefore no sign inversion can occur (hence no detection).

-  

-    

-  

-   The scan will output every little peaks it finds, which may be 
-   too much details for you. In this case, just apply some
-    filters (especially low pass) before running the detection.

-  

-   Template matching

-  

-   The vector used to compute the correlation is a big vector made 
-   with all the time frames for all the tracks (of the template). 
-   F.ex. a template of 100 time frames for 125 electrodes is a vector of 
-   100 * 125 = 12500 dimensions. In this way, we will retrieve only very 
-   specific patterns, both in space and in time.

-  

-   The correlation values does not 
-   take into account the power of the signal, but just its shape.

-  

-   When the current time window first correlates above the threshold, 
-   the scan continues and seeks for the highest peak of correlation 
-   of the period before the correlation goes below the threshold. Well, 
-   sounds difficult to make it in simple words, but simply gives you 
-   what you actually expect! The marker position within the selected 
-   time window is put where the template has its maximum GFP. In fact, 
-   it is not that important, what matters is that the triggers be 
-   put at the same offset for all the windows.

-  

-   The marker position is set at the position of highest GFP. Also 
-   see the Naming Markers options.

-  

-   How the time constraints work

-  

-   Consider a Stability scan on one 
-   track. To create a marker, the condition (plateau) should last within 
-   the given limits. Then the next marker can not start before the gap 
-   is filled:

-  

-    

-  

-   

-    
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-    

-       

-        

-         Condition is false

-       

-        

-         Condition is true

-       

-        

-         Condition is false

-       

-        

-         Condition should last within the time range specified

-       

-        

-         Gap should be at least this long

-       

-         

-       

-         

-       

-        

-         

-       

-       

-        

-         

-         

-        

-       

-        |

-       

-        |

-       

-         

-       

-         

-       

-        

-         

-       

-       

-        | <- Marker insertion

-       

-        Next marker allowed from here ->

-   

-  

-   Merging (nearly) simultaneous markers

-  

-   Merging markers is useful to consolidate the markers resulting from 
-   individual tracks into a more synthetic information. We can get the 
-   information of how many tracks were successful within a short time 
-   range. It can also be used to fusion trigger codes spread across 
-   different tracks.

-  

-   We ran an Above Threshold 0 scan, 
-   first without merging markers (i.e. one marker per track, kind of a 
-   mess), then with merging markers within 8 TF range (and showing the 
-   count of merged markers in the names):

-  

-   

-  

-   Also see the Naming Markers options.

-  

-   Scanning for markers - Results

-  

-   File generated

-  

-   The markers are added to the external .mrk file 
-   associated with the EEG file. Remember to move both files if you move 
-   the EEG to another directory.

-  

-   Scanning for markers - Examples

-  

-   Here are a few examples to get a grasp on all the possibilities from 
-   the combinations of options.

-  

-   Note however that some options could be hard to understand when 
-   combined together. F.ex. scanning for Thresholds Above, plus 
-   shifting to the maximum slope, plus merging simultaneous markers with 
-   a wide range, plus Naming only with a Prefix... Unless you really 
-   want it!

-  

-   Positions of maximum GFP:

-  
    
-   
  • 
-   
    
-    Set Filters with some low pass filter, to 
-    smooth out small irregularities
    
-    
  • Tracks: GFP
    
-    
  • Scanning for: Local Extrema, Max
    
-    
  • One Marker per Track
    
-   

-  

-   Any track above a value:

-  
    
-   
  • 
-   
    
-    Tracks: choose the ones you want to test, or all
    
-    
  • Threshold, Above: set a value
    
-    
  • Condition has to be true for: 1 to 100000 TF 
-    (kind of always true)
    
-    
  • One Marker per Track
    
-   

-  

-   Triggers hard-coded into tracks:

-  
    
-   
  • 
-   
    
-    Tracks: choose the tracks that hold the trigger information
    
-    
  • Periods of Stability
    
-    
  • Condition has to be true for: give a 
-    reasonable interval of time for "good" triggers (i.e. set a 
-    min duration to avoid detecting noise)
    
-    
  • Merged into Single Marker, Tolerance 
-    set to 0 or a very small range.
    
-    
  • Naming Markers: Prefix Off, Relative Index On
    
-   

-  

-   Counting frequency events from tracks:

-  
    
-   
  • 
-   
    
-    Set Filters to Envelope (i.e. band 
-    pass), or do a Frequency analysis 
-    first (like the S-transform)
    
-    
  • Tracks: all
    
-    
  • Threshold, Above: set a value for a 
-    minimum level of detection
    
-    
  • Condition has to be true for: restrict the 
-    duration of the searched event
    
-    
  • Merged into Single Marker, Tolerance 
-    depending on your data (sampling frequency, etc...)
    
-    
  • Naming Markers: Prefix On, Merged Count On
    
-   

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    
+         

+             Average Reference  
+         

+         

+             Toggles on or off the Average Reference.
+             This is equivalent to setting the 
+                 average
+                 reference through the Menu
+             .
+         

+         

+             Brightness  
+         

+         

+             Only when in the Intensity mode can
+             you adjust the brightness / intensity of the colors.
+         

+         

+             This is equivalent to changing the value assigned to the maximum color.
+         

+         

+             See an example here, with the 
+                 MRI
+                 display
+             .
+         

+         

+             Contrast  
+         

+         

+             Contrast does not change the maximum value mapped to the maximum
+             color, but changes the slope of the mapping, increasing or
+             decreasing the color differences between low and high values.
+         

+         

+             See an example here, with the 
+                 MRI
+                 display
+             .
+         

+         

+             Color auto scaling  
+         

+         

+             Sets the maximum volume value to the maximum color value. Put it
+             another way: automatically sets the brightness to match and correctly
+             display the data. Consequently, the brightness
+             buttons become inactive, but still the contrast
+             can be adjusted.
+         

+         

+             Color modes  
+         

+         

+             Cycles through different color tables (black to white, white to
+             black, black to yellow to white, etc...).
+         

+         

+             EEG - Mouse
+         

+         

+             Go here for the mouse actions
+             common to all views.
+         

+         

+             Chart of all mouse operations for EEG
+         

+         

+             
+                 
+                     
+                     
+                     
+                     
+                     
+                 
+                 
+                     
+                     
+                     
+                     
+                     
+                 
+                 
+                     
+                     
+                     
+                     
+                     
+                 
+                 
+                     
+                     
+                     
+                     
+                     
+                 
+                 
+                     
+                     
+                     
+                     
+                     
+                 
+             

+                         

+                             Alternate key
+                         

+                         

+                             

+                                 Mouse button
+                     

+                         

+                             

+                                 None
+                     

+                         

+                             

+                                 Shift
+                     

+                         

+                             

+                                 Control
+                     

+                         

+                             

+                                 Control+Shift
+                     

+                         

+                             

+                                 Left
+                     

+                         

+                             

+                                 time selection

+                                 or

+                                 rotation if 
+                                     in
+                                     3D
+                                 
+                     

+                         

+                             

+                                  
+                     

+                         

+                             

+                                 same as Middle

+                                 or

+                                 zoom if 
+                                     in
+                                     3D
+                                 
+                     

+                         

+                             

+                                 same as Shift Middle
+                     

+                         

+                             

+                                 Middle
+                     

+                         

+                             

+                                 tracks selection
+                     

+                         

+                             

+                                 bad tracks selection
+                     

+                         

+                             

+                                  
+                     

+                         

+                             

+                                  
+                     

+                         

+                             

+                                 Right
+                     

+                         

+                             

+                                 horizontal scrolling

+                                 or

+                                 next/previous tracks
+                     

+                         

+                             

+                                 horizontal zoom

+                                 or

+                                 vertical zoom
+                     

+                         

+                             

+                                  
+                     

+                         

+                             

+                                 baseline offset shifting 
+                     

+                         

+                             

+                                 Double Left
+                     

+                         

+                             

+                                 keep only sub-window
+                     

+                         

+                             

+                                  
+                     

+                         

+                             

+                                  
+                     

+                         

+                             

+                                  
+                     

+         

+         

+              
+         

+         

+             Time selection: left click
+         

+         

+             Click (and extend) the left button to set the current
+             time point/time range:
+         

+         

+             
+         

+         

+             If you hold down the left button, you can 
+                 extend
+                 the cursor
+              to any size you want, even outside the current
+             window. In this case, the window will scroll while you move the
+             cursor outside the window:
+         

+         

+             
+         

+         

+             See also the keyboard way of 
+                 moving
+                 the cursor
+             .
+         

+         

+             Tracks selection: middle click
+         

+         

+             Click (and extend vertically) the middle button to
+             select/deselect some tracks.
+         

+         

+             You can use Control + left click if you don't have a middle
+             button. Also note that you have to click close to the baseline of the
+             track, not on the track itself!
+         

+         

+             The selected tracks are drawn in pink:
+         

+         

+             
+         

+         

+             To deselect some tracks, middle click again on them.
+         

+         

+             To deselect all tracks, middle click somewhere far
+             enough from the tracks, say, around the electrode names.
+         

+         

+             For more controls and possible uses, see the menu Selection.
+         

+         

+             The tracks selection does not interfere with the time
+             selection at all.
+         

+         

+             Bad tracks selection: Shift + middle click
+         

+         

+             Use Shift and click the middle button to
+             set/reset some bad tracks.
+         

+         

+             The bad tracks are drawn in light red:
+         

+         

+             
+         

+         

+             Bad tracks (broken electrode, noisy signal etc...) are taken out of
+             the calculus of the computed tracks,
+             and the number of significant electrodes decreased by their amount.
+             They are also independently rescaled, so that any high amplitudes
+             will not visually degrade the display. You can easily show or remove
+             them through the Selection menu.
+         

+         

+             Horizontal scrolling or Next /
+             Previous tracks: right click
+         

+         

+             Click the right button, then 
+                 drag either
+                 horizontally or vertically
+             .
+         

+         

+             If the initial direction of the mouse is horizontal, the
+             window will be subsequently scrolled horizontally. Otherwise,
+             the scrolling will be applied vertically, to the tracks,
+             by shifting to the next/down tracks
+             or the previous/upper tracks. More
+             intuitive if you try it!
+         

+         

+              
+         

+         

+             The visual hints
+             associated, moving horizontally (time), or vertically (tracks):
+         

+         

+             

+             
+         

+         

+             Horizontal & vertical zoom: Shift +
+             right click
+         

+         

+             Use Shift and click the right button, then 
+                 drag
+                 either horizontally or vertically
+             .
+         

+         

+             The direction you choose will select which dimension will be zoomed
+             in/out: horizontal or vertical.
+         

+         

+             When zooming horizontally, Cartool will center the current view
+             to the current cursor position, which can be handy to quickly
+             recenter your view to a given time frame.
+         

+         

+             See also the next point below to some some tracks specifically.
+         

+         

+              
+         

+         

+             The visual hints
+             associated, for the vertical and horizontal zoom:
+         

+         

+             

+             
+         

+         

+             Relative vertical zoom: Control +
+             Shift + right click
+         

+         

+             Use Control + Shift and click the right button,
+             then drag either horizontally or vertically.
+         

+         

+             This will zoom in/out only the 
+                 
+                     currently
+                     selected tracks
+                 
+             , using the same procedure as the 
+                 global
+                 scaling
+             .
+         

+         

+             If no tracks are selected, then the global scaling applies. The
+             procedure can be repeated as many time, and on any tracks subset, as needed.
+         

+         

+             To reset the scaling to the global default, use the  
+                 
+                     Options
+                     | Reset tracks scaling
+                 
+               menu.
+         

+         

+              
+         

+         

+             This is a way you can emphasize (interesting but too small) or
+             de-emphasize (noisy and big) some particular tracks by giving them a 
+                 local
+                 scaling
+              of their own:
+         

+         
    
+             
  • 
+                 
    
+                     a regular, uniform scaling:
+                 
    
+         

+         

+             
+         

+         
    
+             
  • 
+                 
    
+                     some specific scaling:
+                 
    
+         

+         

+             
+         

+         

+             Finally, note that the rescaling buttons
+             will only work globally, even though some tracks might be selected.
+         

+         

+             Baseline offset shifting: Control +
+             right click
+         

+         

+             Use Control and click the right button, then 
+                 drag
+                 vertically
+             .
+         

+         

+             This will move the whole tracks baseline (axis) up and down. If the
+             data are highly skewed toward an extreme value, this allows the
+             re-center the display around that limit, and then play with the
+             vertical zooming as usual.
+         

+         

+             To manually set a baseline value, or to reset it to its default (i.e.
+             0), see the  
+                 
+                     Options
+                     | Reset baseline offset
+                 
+               menu.
+         

+         

+              
+         

+         

+             See here the default baseline, and a shifted baseline of -150:
+         

+         

+                
+             
+         

+         

+              
+         

+         

+             The visual hints
+             associated when shifting the baseline:
+         

+         

+             
+         

+         

+             Keep only one sub-window: double left click
+         

+         

+             When the EEG tracks are rendered into
+             different sub-windows, double left clicking one of these will
+             switch the display to that single sub-window alone.
+         

+         

+             Drag & Drop
+         

+         

+             You can Drag & Drop any .mrk
+                 file into the window
+             , and all markers from that file fitting the
+             current EEG time range will be added to the current list.
+         

+         

+             EEG - Keyboard
+         

+         

+             Go here and here
+             for the keyboard actions common to all views.
+         

+         

+             Moving cursor
+         

+         

+             With left and right arrows, you move accordingly the 
+                 time
+                 cursor
+             . Another way is to use the mouse.
+             However, using the keyboard is more accurate, and while holding down
+             the key, Cartool will slowly accelerates. When the cursor
+             leaves the last visible time frame, Cartool will scroll the display
+             of an appropriate amount. Altogether with the acceleration, you can
+             easily browse to even huge files very efficiently.
+         

+         

+             To prevent the automatic acceleration, press Control + left
+             or Control + right arrows, so you can go through all time frames.
+         

+         

+             An extended cursor is moved the same way, though it may appear to
+             behave strangely sometimes. In case the cursor is actually wider than
+             the number of time frames currently displayed, moving the cursor
+             forward will show only the end of the cursor. And moving the cursor
+             backward will show only the beginning of the cursor.
+         

+         

+             Next or previous page
+         

+         

+             Use the page down and page up to jump to the next or
+             previous screen respectively. The amount of time frames jumped over
+             is exactly the number of time frames currently displayed. These keys
+             will also slowly accelerate when held down.

+             The cursor will also jump accordingly, that is, it will remain stable
+             within the window.
+         

+         

+             Beginning or end of Eeg
+         

+         

+             Pressing the home key will of course scroll the display
+             to time frame 0, and set the cursor to 0. Conversely, pressing
+             the end key will do the same with the last time frame. The
+             number of time frames displayed is not altered.
+         

+         

+             Quickly creating markers
+         

+         

+             Pressing Control + Numpad 1 to 9 to set the any of the
+             9 possible quick markers:
+         

+         
    
+             
  • 
+                 
    
+                     On first call, Cartool will ask the associated marker name
+                     for that keystroke combination
+                 
    
+             
  • 
+                 
    
+                     On later calls, Cartool will 
+                         create a marker at current
+                         cursor position
+                     , using the marker name entered on first
+                     call
+                 
    
+         

+         

+             Quickly jumping the cursor by blocks
+         

+         

+             Pressing Control + Left or Right arrow to move the
+             cursor backward or forward, of the amount of its current size.
+         

+         

+             F.ex. if the cursor is currently extending from time frame 0 to 99,
+             pressing Control + Right will make the cursor jump to 100 to 199,
+             then 200 to 299 and so on. Combine this with quickly 
+                 creating
+                 markers
+             , then you have a winner combo to quickly browse a file
+             and tag blocks of data.
+         

+         

+             EEG - Menus
+         

+         

+             Edit menu
+         

+         
    
+             
    
+                 Copy as Text
+             
    
+             
      
+                 
      
+                     Copy to the clipboard the current 
+                         selected
+                         tracks
+                     , and for the current 
+                         selected
+                         time
+                     , in a text format. If no tracks are specially selected,
+                     then all tracks are taken. The output format is: a row holds all
+                     electrodes of 1 time frame, and the number of rows is the number of 
+                         time
+                         frames
+                     . Values are tab separated, with new line at
+                     the end of each row, so you can properly paste both in a text editor
+                     and Excel.
+                 
      
+             
    
+             
    
+                 Copy as Bitmap
+             
    
+             
      
+                 
      
+                     Do a snapshot in the clipboard, see here.
+                 
      
+             
    
+             
    
+                 Export Tracks
+             
    
+             
+         

+         

+             Selection menu
+         

+         

+             This (extensive) menu is about tracks selection and categorization.
+         

+         

+             
+                 Please note that only the non-trivial functions will be commented,
+                 otherwise each command is considered self-explanatory!
+             
+         

+         

+             Main list
+         

+         
    
+             
    
+                 Keep current selection
+             
    
+             
      
+                 
      
+                     ..on display
+                 
      
+             
    
+             
    
+                 Exclude current selection
+             
    
+             
      
+                 
      
+                     ..from display
+                 
      
+             
    
+             
    
+                 Clear selection
+             
    
+             
    
+                 Select all tracks
+             
    
+             
    
+                 Select all visible tracks
+             
    
+             
    
+                 Invert selection
+             
    
+             
    
+                 Select tracks above threshold
+             
    
+             
      
+                 
      
+                     Tracks that are in absolute value above a user-specified threshold.
+                 
      
+             
    
+             
    
+                 Select tracks from a list
+             
    
+             
      
+                 
      
+                     The user provides a list of tracks name to select from
+                 
      
+             
    
+         

+         

+             Bad tracks
+         

+         
    
+             
    
+                 Set current selection as Bad tracks
+             
    
+             
      
+                 
      
+                     Flags the selected tracks as bads, which removes them from some
+                     computation, like GFP, Disssimilarity and Average.
+                 
      
+             
    
+             
    
+                 Restore all bad tracks to Normal
+             
    
+             
    
+                 Restore only the selected bad tracks
+             
    
+             
    
+                 Keep only the current bad tracks
+             
    
+             
    
+                 Exclude the current bad tracks
+             
    
+             
    
+                 Select current bad tracks
+             
    
+             
      
+                 
      
+                     ..from either the current selection, if any, or from the current
+                     displayed tracks otherwise.
+                 
      
+             
    
+             
    
+                 Deselect current bad tracks
+             
    
+             
      
+                 
      
+                     ..from either the current selection, if any, or from the current
+                     displayed tracks otherwise.
+                 
      
+             
    
+             
    
+                 Select current non-bad tracks
+             
    
+             
      
+                 
      
+                     ..from either the current selection, if any, or from the current
+                     displayed tracks otherwise.
+                 
      
+             
    
+             
    
+                 Select current non-bad / non-aux tracks
+             
    
+             
      
+                 
      
+                     ..from either the current selection, if any, or from the current
+                     displayed tracks otherwise.
+                 
      
+             
    
+         

+         

+             Auxiliary tracks
+         

+         
    
+             
    
+                 Set current selection as Auxiliary tracks
+             
    
+             
      
+                 
      
+                     Flags the selected tracks as auxiliaries, like ECG, EOG etc...
+                 
      
+                 
      
+                     Usually, Cartool will ask you if you want to remember your new
+                     auxiliaries configuration as the default (for your current type of
+                     file only). If yes, any future opening of that type of file will use
+                     your configuration. If no, your configuration will only apply to the
+                     lifetime of your current opened file.
+                 
      
+             
    
+             
    
+                 Restore all auxiliary tracks to Normal
+             
    
+             
      
+                 
      
+                     Same remark as above.
+                 
      
+             
    
+             
    
+                 Restore only the selected auxiliary tracks
+             
    
+             
      
+                 
      
+                     Same remark as above.
+                 
      
+             
    
+             
    
+                 Restore auxiliaray tracks to default
+             
    
+             
      
+                 
      
+                     Reset the auxiliary configuration to its default (for your current
+                     type of file only), forgetting any override you may have done before.
+                 
      
+             
    
+             
    
+                 Keep only the current auxiliary tracks
+             
    
+             
    
+                 Exclude the current auxiliary tracks
+             
    
+             
    
+                 Select current auxiliary tracks
+             
    
+             
      
+                 
      
+                     ..from either the current selection, if any, or from the current
+                     displayed tracks otherwise.
+                 
      
+             
    
+             
    
+                 Deselect current auxiliary tracks
+             
    
+             
      
+                 
      
+                     ..from either the current selection, if any, or from the current
+                     displayed tracks otherwise.
+                 
      
+             
    
+             
    
+                 Select current non-auxiliary tracks
+             
    
+             
      
+                 
      
+                     ..from either the current selection, if any, or from the current
+                     displayed tracks otherwise.
+                 
      
+             
    
+             
    
+                 Select current non-bad / non-aux tracks
+             
    
+             
      
+                 
      
+                     ..from either the current selection, if any, or from the current
+                     displayed tracks otherwise.
+                 
      
+             
    
+         

+         

+             Tracks analysis
+         

+         

+             
+                 (note that these are currently experimental functions, but you
+                 risk nothing by trying/using them!)
+             
+         

+         
    
+             
    
+                 Search Flat tracks
+             
    
+             
      
+                 
      
+                     Select tracks with constant values, which usually were not recorded.
+                     Note that the reference track should be kept and is/should not be
+                     selected by this method:
+                 
      
+                 
      
+                     
+                 
      
+             
    
+             
    
+                 Search Broken / jerky tracks
+             
    
+             
      
+                 
      
+                     Select highly saturated, or very random tracks, which clearly haven't
+                     recorded anything EEG-like:
+                 
      
+                 
      
+                     
+                 
      
+             
    
+             
    
+                 Search Outlier / noisy tracks
+             
    
+             
      
+                 
      
+                     Select tracks that do look like EEG, but of very low
+                     informational quality. These tracks stand out from the others, even
+                     after filtering, and therefor greatly degrade the GFP (or Standard Deviation):
+                 
      
+                 
      
+                     
+                 
      
+             
    
+             
    
+                 Search Altogether: Flat + Broken + Outlier tracks
+             
    
+             
      
+                 
      
+                     Use all three criterion above to search for globally artefacted
+                     tracks. First image shows the selection, second image shows the
+                     selection flagged as bad tracks, clearing up the display:
+                 
      
+                 
      
+                     
+                 
      
+             
    
+         

+         

+             Remarks on the tracks analysis:
+         

+         
    
+             
  • 
+                 
    
+                     The analysis goes through a lot of statistics computed 
+                         on
+                         all electrodes
+                      and on the whole time range (minus the
+                     first and last 10%, and sometimes minus the eye blinks epochs). The
+                     results are tracks that are globally bad all over the recording,
+                     not at some specific epochs like eye blinks.
+                 
    
+             
  • 
+                 
    
+                     The analysis uses your current filters, because this is what
+                     will matter for your processing at hand. Changing the filters will
+                     likely change the results of the analysis, like a high-pass that can
+                     help recover a drifting track, or a Notch with line interference. It
+                     shouldn't be dramatically different, though.
+                 
    
+             
  • 
+                 
    
+                     The analysis is done with the recording reference,
+                     re-referencing is not used.
+                 
    
+             
  • 
+                 
    
+                     The 3 processing run in increasing complexities, so in case of
+                     doubts, run them sequentially from the first one to the last one.
+                 
    
+             
  • 
+                 
    
+                     Bear in mind that the result is just a track selection, and
+                     that no action has been really taken. It is up to you to just ignore
+                     the result, or to manually include / exclude some other tracks, and
+                     to actually flag the selection as bad tracks.
+                 
    
+             
  • 
+                 
    
+                     The analysis is primarily targetting EEG recordings, because
+                     it contains all the original noise and artefacts. You can run it on
+                     ERPs, though, but the averaging process might have hidden some of the artefacts.
+                 
    
+         

+         

+             Markers menu
+         

+         

+             Don't remember what is a marker, a trigger
+             or an event? or the .mrk
+                 marker file format
+             ?
+         

+         

+              
+         

+         
    
+             
    
+                 Add marker at current cursor position
+             
    
+             
+             
    
+                 Delete markers within cursor range
+             
    
+             
      
+                 
      
+                     Deletes only the markers that are entirely included within the
+                     current cursor position. Be careful, no undo is possible.
+                 
      
+             
    
+             
    
+                 Delete markers by names
+             
    
+             
+             
    
+                 Delete all markers
+             
    
+             
      
+                 
      
+                     Delete all markers, for the whole file. Be careful, no undo is possible.
+                 
      
+             
    
+             
    
+                 Search for marker
+             
    
+             
+             
    
+                 Next hit
+             
    
+             
+             
    
+                 Previous hit
+             
    
+             
+             
    
+                 Rename markers within cursor range
+             
    
+             
      
+                 
      
+                     Force renaming all markers within the current cursor range.
+                 
      
+             
    
+             
    
+                 Rename all markers
+             
    
+             
      
+                 
      
+                     Specify a substring to be replaced (any type of characters), and a
+                     replacement substring. It will run through all occurences within a
+                     marker name, replacing the old string by the new one, and for all
+                     markers. If the replacement string is empty, this will delete the
+                     searched string.
+                 
      
+                 
      
+                     Applications are numerous, as replacing spaces by "_", or
+                     the other way round, changing esoteric codes (173) into meaningful
+                     messages ("Elephant sound"), merging different codes into a
+                     single one, and so on.
+                 
      
+             
    
+             
    
+                 Merge exact overlapping markers
+             
    
+             
      
+                 
      
+                     All markers that perfectly overlap (same starting points and
+                     same ending point) will be merged together, also merging their names.
+                 
      
+             
    
+             
    
+                 Merge identical contiguous markers
+             
    
+             
      
+                 
      
+                     Merge markers with the exact same name and that are contiguous in
+                     time. This can be useful if you have labelled blocks of data that you
+                     want to re-group into bigger blocks.
+                 
      
+             
    
+             
    
+                 Scanning tracks to generate markers
+             
    
+             
+             
    
+                 Duplicate triggers into markers
+             
    
+             
      
+                 
      
+                     Copies all triggers into markers,
+                     which allows you to further process / edit them, which is not the
+                     case for the triggers.
+                 
      
+                 
      
+                     You also have to select the correct display,
+                     if you want to see only the markers, as otherwise you will
+                     see both the triggers and the markers, which can be a little bit confusing.
+                 
      
+             
    
+             
    
+                 Split bitwise triggers / markers names
+             
    
+             
      
+                 
      
+                     This will scan the currently displayed triggers or markers, and will
+                     split them according to their names, creating new markers. The idea
+                     is to break each name into its binary components, f.ex.
+                 
      
+                 
        
+                     
      • 
+                         
        
+                             "24" will be splitted into markers "16" and "8";
+                         
        
+                     
      • 
+                         
        
+                             "17" into "16" and "1";
+                         
        
+                     
      • 
+                         
        
+                             "6" into "4" and "2";
+                         
        
+                     
      • 
+                         
        
+                             "3" into "2" and "1".
+                         
        
+                 
      
+                 
      
+                     To be more selective, a mask has to be specified before running the
+                     process. Only the bits set to 1 in the binary representation of that
+                     mask will be processed. F.ex. if the mask is 255 (1111 1111 in
+                     binary), we will have all the markers of the previous example.
+                     However, if the mask is 17 (0000 1001 in binary), the results would
+                     only be "16", "16" and "1", nothing,
+                     "1". In this way, you can restrict the generated markers.
+                 
      
+                 
      
+                     This process is applied only to the currently displayed type of
+                     triggers / markers. However, only markers are generated.
+                 
      
+                 
      
+                     The names have to be integer, you can not split triggers whose names
+                     would be "Eyes open" or "Abcd"!
+                 
      
+             
    
+             
    
+                 Manage the list of marker names
+             
    
+             
      
+                 
      
+                     Brings the list of currently known marker names. Then you can add
+                     a new name, modify existing names, or delete names.
+                 
      
+                 
      
+                     At least one name should remain in the list, though.
+                 
      
+             
    
+             
    
+                 Import markers from file
+             
    
+             
      
+                 
      
+                     Reads another .mrk file and copies its markers.
+                 
      
+             
    
+             
    
+                 Switch to another marker file
+             
    
+             
      
+                 
      
+                     (Advanced feature) This will switch the currently associated .mrk
+                     file (storing the markers), to another .mrk file. Any
+                     subsequent updates will then occur on this file.
+                 
      
+             
    
+             
    
+                 Display
+                 
      
+                     None
+                     
        
+                         No triggers or markers of any sorts are displayed
+             
        
+         
      
+         
      
+             Events
+             
        
+                 Toggles on or off the display of events
+         
        
+         
      
+         
      
+             Triggers
+             
        
+                 Toggles on or off the display of triggers
+         
        
+         
      
+         
      
+             Markers
+             
        
+                 Toggles on or off the display of markers
+         
        
+         
      
+         
      
+             All
+             
        
+                 Shows all available events, triggers and markers
+         
        
+         
      
+         
    
+         
    
+             Filtering display
+         
    
+         
      
+             
      
+                 Show only the triggers / markers that successfully match a 
+                     
+                         string
+                         expression
+                     
+                 .
+             
      
+             
      
+                 This is a very useful feature to show a restricted subset of markers,
+                 hiding all the others, and therefore increasing the display
+                 readability when too many markers coexist together.
+             
      
+         
    
+         
    
+              
+         
    
+         

+         

+             Notes on marker files
+         

+         

+             When all markers have been deleted, the .mrk file
+             associated to the Eeg file will be also deleted. Conversely,
+             when the very first marker is created, the .mrk file is also created.
+         

+         

+             For security reasons, any time you add or remove any single marker,
+             the .mrk file is immediately updated on disk. This way,
+             in case of any crash, your markers will be securely saved.
+         

+         

+             Options menu
+         

+         
    
+             
    
+                 Reference
+                 
      
+                     As in file
+                     
        
+                         No subtraction occurs, the data are shown exactly as they are
+                         
+                             stored
+                             in the Eeg file
+                          (then you should know which reference was used...)
+             
        
+         
      
+         
      
+             Average
+             
        
+                 After applying any filters, the
+                 mean value of the tracks is
+                 computed and
+                 subtracted to all tracks. This is repeated for
+                 all time frames idependently. See the
+                 formulas,
+                 and the
+                 equivalent button.
+         
        
+         
      
+         
      
+             Single track
+             
        
+                 After applying any filters, the
+                 value of the
+                 
+                     specified
+                     track is subtracted
+                  to all tracks. This is repeated for all time
+                 frames idependently.
+         
        
+         
      
+         
      
+             Multiple tracks
+             
        
+                 After applying any filters, the
+                 average value of the
+                 
+                     specified
+                     tracks is subtracted
+                  to all tracks. This is repeated for all
+                 time frames idependently.
+         
        
+         
      
+         
      
+             Montage
+             
        
+                 First requires a
+                 .mtg
+                 
+                     montage file
+                 . After applying any filters, and according to the
+                 montage specifications, any mix of
+                 differences between pairs of tracks
+                 or
+                 single tracks values are shown. This is repeated for all
+                 time frames independently. This affects only the display, not the
+                 data themselves, so you can not export the results.
+                 
        
+                 Within one of
+                 these modes, the
+                 results are correctly positionned between the two subtracted
+                 electrodes, giving a visual cue of your montage.
+         
        
+         
      
+         
    
+         
    
+             Time
+             
      
+                 Show Date
+                 
        
+                     If the date information is available from the Eeg file, either choose
+                     to show it or not.
+         
        
+         
      
+         
      
+             Show Time
+             
        
+                 If the time information (in hours/minutes/seconds etc...) is
+                 available in the Eeg file, either choose to show it or not.
+         
        
+         
      
+         
      
+             Absolute time, from the recording
+             
        
+                 Choose to use the absolute time, the one when the recording has been
+                 done, f.ex. starting at 9h37m10s.
+                 
        
+                 You can then relate some events in the EEG to the ones in
+                 "real" life, like seasures.
+         
        
+         
      
+         
      
+             Relative time, origin at the beginning
+             
        
+                 Set the time origin at the first Time Frame recorded, giving you a
+                 relative time starting at 0h0m0s.
+         
        
+         
      
+         
      
+             Relative time, arbitrary origin
+             
        
+                 Set the time origin to an arbitrary position in the file. By default,
+                 Cartool will propose the current position of the cursor, or you can
+                 give any value as a relative offset from the beginning of the file.
+                 
        
+                 You can give a position that is not within the relative time range of
+                 the file, and even a negative value.
+                 
        
+                 This is the feature used to automatically set the origin if a marker
+                 is found with the name "Origin". The origin is drawn with
+                 the
+                 little vertical bar on the time axis:
+                 
        
+                 
+         
        
+         
      
+         
      
+             Go to time origin
+             
        
+                 Quickly move the Time Cursor to the time origin.
+         
        
+         
      
+         
    
+         
    
+             Set Display Scaling
+         
    
+         
      
+             
      
+                 Ask the user (you actually...) to give the maximum amplitude to be
+                 shown in the current window. Works until you rescale the window.
+             
      
+         
    
+         
    
+             Set Time Window
+         
    
+         
      
+             
      
+                 Give a time range for the current page. Default input is in
+                 milliseconds, but you can override it by adding "s" for
+                 seconds, f.ex.: 10s, 2.5s etc...
+             
      
+         
    
+         
    
+             Reset Tracks Scaling
+         
    
+         
      
+             
      
+                 Some tracks might have user-defined 
+                     relative
+                     scalings
+                 , making them appear greater or smaller then their
+                 peers. This will reset these differential scalings. If no tracks are selected,
+                 all tracks are reseted, otherwise only the selected ones will be.
+             
      
+         
    
+         
    
+             Specify a Baseline Offset
+         
    
+         
      
+             
      
+                 Vertically shift the whole tracks of the specified amount, setting it
+                 as the new the baseline value.
+             
      
+         
    
+         
    
+             Reset Baseline Offset
+         
    
+         
      
+             
      
+                 Reset to 0 the baseline offset.
+             
      
+         
    
+         
    
+             Line Width
+         
    
+         
      
+             
      
+                 Specify a line width. Default is 0, which activates the 
+                     Smart
+                     Line Width
+                  features. This will choose the best line width
+                 according to the context:
+             
      
+             
        
+                 
      • 
+                     
        
+                         A high density of time points, and / or a high number of tracks
+                         will select the thinnest line width available.
        
+                 
      • 
+                     Less tracks, or less time points, or bigger window,
+                     or more zoom will little by little increase the line width.
        
+                 
      • 
+                     Superimpose mode will always select the thinnest
+                     line width.
        
+             
      
+             
      
+                 If not 0, the width specified will be used as is. Valid values
+                 will depend on your graphic card,
+                 including fractional numbers, and 1 being the default.
+             
      
+         
    
+         
    
+             Show/hide Baseline Axis
+         
    
+         
      
+             
      
+                 Nothing to add.
+             
      
+         
    
+         
    
+             Goto Another Session / Block
+         
    
+         
      
+             
      
+                 If the Eeg file embeds multiple recordings, sometime known as
+                 sessions or blocks, you can shift to another one. See this button.
+             
      
+         
    
+         
    
+             Easy publish
+         
    
+         
      
+             
      
+                 This feature is not yet implemented, but will be very soon. For sure,
+                 it will scan your data, analyse them, do all the tests, output the
+                 figures, and build an article ready to be accepted in the highest
+                 ranked publications. And everything done in 5 minutes while playing
+                 your favorite mp3 playlist.
+             
      
+         
    
+         

+         

+             Scanning for Markers
+         

+         

+             This is a versatile way to 
+                 scan tracks for some propertie to
+                 generate some
+             markers. The
+             markers generated can either be used for display (i.e. where
+             the interesting parts of the data are), or for later processing
+             (like averaging).
+         

+         

+             At the end of the chapter, there are a few examples,
+             if you get confused.
+         

+         

+              
+         

+         

+             Scanning methods
+         

+         

+             There are four methods to scan tracks:
+         

+         
    
+             
  • 
+                 
    
+                     Periods of Stability: used when tracks contain kind of on/off,
+                     plateau-like encoding (like hard-wired triggers).
+                 
    
+             
  • 
+                 
    
+                     Local Extrema: used to search for local minima and maxima of
+                     tracks (including the GFP).
+                 
    
+             
  • 
+                 
    
+                     Thresholds: used to detect when tracks go beyond or fall below
+                     a given threshold.
+                 
    
+             
  • 
+                 
    
+                     Template Matching: used to detect a spatio-temporal pattern on
+                     all tracks at once.
+                 
    
+         

+         

+              
+         

+         

+             The markers resulting from the scan are added to the EEG's associated .mrk file,
+             which you can edit or re-process yourself for more advanced purposes.
+         

+         

+             There is certainly a trial and error phase before you find the
+             right parameters. It may be a good idea to first select a short time
+             interval and/or only a few tracks before running the scan on the full
+             file. Also don't forget to delete
+                 previous markers
+              before re-doing a whole scan, otherwise they
+             will simply cumulate!
+         

+         

+             Scanning for Markers dialog
+         

+         

+             

+                 
+             

+         

+         

+             
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+             

+                         

+                             What to Scan
+                     

+                         

+                              
+                     

+                         

+                             Tracks:
+                     

+                         

+                             These are the tracks to analyse.
+                         

+                         

+                             Each track is analysed independently of the others (except
+                             with Template Matching, which
+                             operates on maps, i.e. on all tracks at once).
+                         

+                         

+                             Selecting some tracks from the
+                             display before calling this dialog will pre-fill this field.
+                     

+                         

+                             Time Period:
+                     

+                         

+                             The time range to scan.
+                         

+                         

+                             These fields are pre-filled with the 
+                                 current
+                                 time selection
+                             , or the whole time range of the file.
+                     

+                         

+                             Scanning for
+                     

+                         

+                              
+                     

+                         

+                             Periods of Stability
+                     

+                         

+                             A track has to remain on a constant level for some time. The
+                             level itself does not matter (anything non-zero), the track has just
+                             to be constant.
+                     

+                         

+                             Local Extrema
+                     

+                         

+                             Finding local minima and/or maxima.
+                     

+                         

+                             Min
+                     

+                         

+                             Scan for local minimum.
+                         

+                         

+                             Use some low-pass filter to reduce the
+                             sensitivity / scale of this detection.
+                         

+                         

+                             See this note.
+                     

+                         

+                             Max
+                     

+                         

+                             Scan for local maximum.
+                         

+                         

+                             Use some low-pass filter to reduce the
+                             sensitivity / scale of this detection.
+                         

+                         

+                             See this note.
+                     

+                         

+                             Thresholds
+                     

+                         

+                             A track has to be above or below some threshold.
+                         

+                         

+                             Note that both above and below criterion can be selected
+                             simultaneously. In that case, you end up with an interval testing.
+                     

+                         

+                             Test if Above:
+                     

+                         

+                             The track has to be above the specifed value, positive or negative.
+                     

+                         

+                             Test if Below:
+                     

+                         

+                             The track has to be below the specifed value, positive or negative.
+                     

+                         

+                             Set marker position to:
+                     

+                         

+                              
+                     

+                         

+                             First TF past threshold
+                     

+                         

+                             The marker is strictly inserted at the first TF where
+                             the test is found positive.
+                     

+                         

+                             Highest slope around threshold
+                     

+                         

+                             The detected position will 
+                                 drift to wherever side which has the
+                                 highest slope
+                             , and will stop there.
+                         

+                         

+                             The purpose of this option is to help align raising-edge events.
+                     

+                         

+                             Template Matching
+                     

+                         

+                             This has to be thought as trying to find a sequence of maps in
+                             the data. Tracks are not considered individually, but as a whole
+                             pattern (a map). Plus, the maps also evolve in time.
+                         

+                         

+                             See this note for more details about how 
+                                 template
+                                 matching
+                              is done here.
+                     

+                         

+                             Template file:
+                     

+                         

+                             The file with the template to serach for. It should have the same
+                             number of electrodes as the EEG file to scan.
+                         

+                         

+                             It can be any kind of EEG file format.
+                     

+                         

+                             Correlation above which to accept:
+                     

+                         

+                             Specifies the correlation value (in percentage) above which the test
+                             will be positive.
+                         

+                         

+                             Correlation does account for sign, that is, correlation -90 is
+                             below 50.
+                     

+                         

+                             Time Constraints
+                     

+                         

+                              
+                     

+                         

+                             Condition has to be true between ... and
+                             ... [TF]
+                     

+                         

+                             Constraint the test chosen by defining time limits.
+                         

+                         

+                             F.ex. we can be interested in short duration plateau, at least 3 TF
+                             longs, but shorter than 30 TF. In case you don't care, set a wide
+                             range, like from 1 to 10000!
+                         

+                         

+                             These fields don't apply to local extrema, which by definition are
+                             only 1 TF long.
+                         

+                         

+                             See this note to visualize 
+                                 how the time
+                                 constraints work
+                             .
+                     

+                         

+                             Then condition has to be false for ... [TF]
+                     

+                         

+                             Set the minimum amount of time after the test fails before a new
+                             marker can start again. Should be at least 1.
+                         

+                         

+                             See this note to visualize 
+                                 how the time
+                                 constraints work
+                             .
+                     

+                         

+                             Simultaneous markers:
+                     

+                         

+                             Each track can generate its own marker, so we can deal with this.
+                         

+                         

+                             These options are off when 
+                                 Scanning for
+                                 a template
+                             .
+                     

+                         

+                             One Marker per Track
+                     

+                         

+                             Let each simultaneous marker remain that way.
+                         

+                         

+                             Use the Naming Markers options to
+                             help sort out who is who!
+                     

+                         

+                             Merged into Single Marker
+                     

+                         

+                             Post-process markers that lie in a given range, and merge them into a
+                             single one. See this note.
+                         

+                         

+                             Also see the Naming Markers 
+                             to also merge the names.
+                     

+                         

+                             Tolerance [TF]
+                     

+                         

+                             Give a maximum time extent within which "simultaneous" is meant.
+                         

+                         

+                             Set to 0 to consider only perfectly aligned markers.
+                     

+                         

+                             Naming Markers
+                     

+                         

+                             You can tune the markers' name to your liking.
+                     

+                         

+                             Beginning with Prefix
+                     

+                         

+                             Optionally start all the markers with this prefix.
+                         

+                         

+                             By default, it reflects the kind of Scanning method
+                             you chose, like "Stab", "Thresh", etc...
+                     

+                         

+                             Including name
+                     

+                         

+                             Optionally include the track name.
+                         

+                         

+                             When Scanning for a template, this
+                             is replaced by the Template file name.
+                         

+                         

+                             Off when merging markers.
+                     

+                         

+                             Ending with value:
+                     

+                         

+                             The following options are quite context sensitive!
+                     

+                         
    
+                             
    
+                                 None
+                     

+                         

+                             What it says.
+                     

+                         
    
+                             
    
+                                 Track Value
+                     

+                         

+                             The value of the track that generates the marker at that position.
+                         

+                         

+                             Useful f.ex. to retrieve the Max value of a track. When 
+                                 Scanning
+                                 for a template
+                             , this is replaced with the Correlation value.
+                         

+                         

+                             Off when merging markers.
+                     

+                         
    
+                             
    
+                                 Relative Index
+                     

+                         

+                             Add an index corresponding to the relative position of the track
+                             generating the marker.
+                         

+                         

+                             Indexes are not 1, 2, 3, 4... but in powers of 2, like: 
+                                 1,
+                                 2, 4, 8
+                             ... So we can add these values when  
+                                 merging
+                                 markers
+                              together: f.ex. tracks 3 and 4 together will produce a
+                             code of 4 + 8 = 12. If you don't see the use of this, well,
+                             just forget it!
+                         

+                         

+                             Off when Scanning for a template.
+                     

+                         
    
+                             
    
+                                 Merged Count
+                     

+                         

+                             When (and only when) merging markers,
+                             add a count of how many markers were doomed to be merged.
+                         

+                         

+                             Off when Scanning for a template.
+                     

+                         

+                             Process
+                     

+                         

+                             Runs the scan.
+                         

+                         

+                             This button remains 
+                                 disabled until all the parameter
+                                 dialogs have received enough (and consistent) informations
+                             .
+                     

+                         

+                             Cancel
+                     

+                         

+                             Quit the dialog.
+                     

+                         

+                             Help
+                     

+                         

+                             Launch the Help to the right page (should be here...).
+                     

+         

+         

+              
+         

+         

+             Scanning for markers - Technical points & hints
+         

+         

+             Filtering & reference
+         

+         

+             The scan is run on the tracks as they appear to you, that is with the
+             current reference and filters.
+             Therefor changing these settings can dramatically affect the
+             markers. This can actually be used for the best, for example when
+             searching for local maxima.
+         

+         

+             Stopping the scan
+         

+         

+             Just press Escape to get out of a lengthy detection...
+         

+         

+             Local Extrema
+         

+         

+             The detection occurs at the reversal of the signs of 2 successive derivatives.

+             If there is a plateau on either side, this will make one of the
+             derivative null, therefore no sign inversion can occur (hence no detection).
+         

+         

+              
+         

+         

+             The scan will output every little peaks it finds, which may be
+             too much details for you. In this case, just apply 
+                 
+                     some
+                     filters
+                 
+              (especially low pass) before running the detection.
+         

+         

+             Template matching
+         

+         

+             The vector used to compute the correlation is a 
+                 big vector made
+                 with all the time frames for all the tracks
+              (of the template).
+             F.ex. a template of 100 time frames for 125 electrodes is a vector of
+             100 * 125 = 12500 dimensions. In this way, we will retrieve only very
+             specific patterns, both in space and in time.
+         

+         

+             The correlation values does not
+             take into account the power of the signal, but just its shape.
+         

+         

+             When the current time window first correlates above the threshold,
+             the scan continues and seeks for the highest peak of correlation
+             of the period before the correlation goes below the threshold. Well,
+             sounds difficult to make it in simple words, but simply gives you
+             what you actually expect! The marker position within the selected
+             time window is put where the template has its maximum GFP. In fact,
+             it is not that important, what matters is that the triggers be
+             put at the same offset for all the windows.
+         

+         

+             The marker position is set at the position of highest GFP. Also
+             see the Naming Markers options.
+         

+         

+             How the time constraints work
+         

+         

+             Consider a Stability scan on one
+             track. To create a marker, the condition (plateau) should last within
+             the given limits. Then the next marker can not start before the gap
+             is filled:
+         

+         

+              
+         

+         

+             

+                 
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                 

+                             

+                                 

+                                     Condition is false
+                         

+                             

+                                 

+                                     Condition is true
+                         

+                             

+                                 

+                                     Condition is false
+                         

+                             

+                                 

+                                     Condition should last within the time range specified
+                         

+                             

+                                 

+                                     Gap should be at least this long
+                         

+                             

+                                  
+                             

+                             

+                                  
+                             

+                             

+                                 

+                                     

+                         

+                             

+                                 

+                                     

+                                 

+                             

+                             

+                                 |
+                             

+                             

+                                 |
+                         

+                             

+                                  
+                             

+                             

+                                  
+                             

+                             

+                                 

+                                     

+                         

+                             

+                                 | <- Marker insertion
+                         

+                             

+                                 Next marker allowed from here ->
+                         

+             

+         

+         

+             Merging (nearly) simultaneous markers
+         

+         

+             Merging markers is useful to consolidate the markers resulting from
+             individual tracks into a more synthetic information. We can get the
+             information of how many tracks were successful within a short time
+             range. It can also be used to fusion trigger codes spread across
+             different tracks.
+         

+         

+             We ran an Above Threshold 0 scan,
+             first without merging markers (i.e. one marker per track, kind of a
+             mess), then with merging markers within 8 TF range (and showing the
+             count of merged markers in the names):
+         

+         

+             
+         

+         

+             Also see the Naming Markers options.
+         

+         

+             Scanning for markers - Results
+         

+         

+             File generated
+         

+         

+             The markers are added to the external .mrk file
+             associated with the EEG file. Remember to move both files if you move
+             the EEG to another directory.
+         

+         

+             Scanning for markers - Examples
+         

+         

+             Here are a few examples to get a grasp on all the possibilities from
+             the combinations of options.
+         

+         

+             Note however that 
+                 some options could be hard to understand when
+                 combined together
+             . F.ex. scanning for Thresholds Above, plus
+             shifting to the maximum slope, plus merging simultaneous markers with
+             a wide range, plus Naming only with a Prefix... Unless you really
+             want it!
+         

+         

+             Positions of maximum GFP:
+         

+         
    
+             
  • 
+                 
    
+                     Set Filters with some low pass filter, to
+                     smooth out small irregularities
    
+             
  • Tracks: GFP
    
+             
  • Scanning for: Local Extrema, Max
    
+             
  • One Marker per Track
    
+         

+         

+             Any track above a value:
+         

+         
    
+             
  • 
+                 
    
+                     Tracks: choose the ones you want to test, or all
    
+             
  • Threshold, Above: set a value
    
+             
  • 
+                 Condition has to be true for: 1 to 100000 TF
+                 (kind of always true)
    
+             
  • One Marker per Track
    
+         

+         

+             Triggers hard-coded into tracks:
+         

+         
    
+             
  • 
+                 
    
+                     Tracks: choose the tracks that hold the trigger information
    
+             
  • Periods of Stability
    
+             
  • 
+                 Condition has to be true for: give a
+                 reasonable interval of time for "good" triggers (i.e. set a
+                 min duration to avoid detecting noise)
    
+             
  • 
+                 Merged into Single Marker, Tolerance
+                 set to 0 or a very small range.
    
+             
  • Naming Markers: Prefix Off, Relative Index On
    
+         

+         

+             Counting frequency events from tracks:
+         

+         
    
+             
  • 
+                 
    
+                     Set Filters to Envelope (i.e. band
+                     pass), or do a Frequency analysis
+                     first (like the S-transform)
    
+             
  • Tracks: all
    
+             
  • 
+                 Threshold, Above: set a value for a
+                 minimum level of detection
    
+             
  • 
+                 Condition has to be true for: restrict the
+                 duration of the searched event
    
+             
  • 
+                 Merged into Single Marker, Tolerance
+                 depending on your data (sampling frequency, etc...)
    
+             
  • Naming Markers: Prefix On, Merged Count On
    
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+     

  
 
\ No newline at end of file
diff --git a/docs/ReferenceGuide/esi-display.html b/docs/ReferenceGuide/esi-display.html
index ce096388..34214542 100644
--- a/docs/ReferenceGuide/esi-display.html
+++ b/docs/ReferenceGuide/esi-display.html
@@ -2,983 +2,1494 @@
  
   Inverse Solutions Display
  
- 
-  

-   Inverse Solutions Display

-  

-    

-  

-   If you don't know how to get this display on the first hand, please read
-    this topic first. Also note that very often Inverse Solutions 
-   will be nicknamed IS.

-  

-   You can compute the inverse 
-   matrices here, or compute the 
-   results of inverse solutions from EEG (or frequency) files.

-  

-   Buttons

-  

-     

-  

-     

-  

-   Display modes:

-  

-    

-  

-   

-  

-   

-  

-      

-  

-    

-  

-      

-  

-   

-  

-   

-  

-   Mouse

-  

-   Menus

-  

-   Edit

-  
-  

-   Search

-  
-  

-   Regularization

-  
-  

-   Options

-  
-  

-   Technical points

-  

-   How do I get this display?

-   How do I compute the Inverse Solutions matrices?

-   Matrix results: scalar of vectorial

-   Time Averaging
Time Sequence

-   Time Animation
Combining 2D IS and 3D IS

-   Changing the color of the MRI

-   Interpolating between solution points

-   Solution points distribution

-  

-   Inverse Solutions Display - Buttons

-  

-   Display modes

-  

-     

-  

-   Your display will depend mainly on these 5 buttons. Most of 
-   the time their effects combine together to provide some rich 
-   output, so knowing their roles is fundamental to get the most of this display!

-  

-   Show Inverse Solution on 2D clipping 
-   planes  

-  

-   The IS will be drawn in 2D (flat) on the current clipping
-    planes, the values seen are the ones intersecting those planes.

-  

-   The button cycles between 3 states:

-  
    
-   
  • 
-   
    
-    Nothing (i.e. no 2D drawing)
    
-    
  • Drawing with transparency for the lowest values
    
-    
  • Opaque drawing.
    
-   

-  

-    

-  

-   See an example, on top of a single MRI clipping plane 
-   (you can set all 3 planes if you wish):

-  

-   

-  

-   Be aware that if no clipping planes are set, there will 
-   be nothing to see!

-  

-   However, you can have a clipping plane selected 
-   without any MRI rendering. This will draw 
-   only the IS, as f.ex.:

-  

-   

-  

-   Finally, note that the coloring only occurs where the MRI
-    mask provided has non-null values.

-  

-   Show Inverse Solution in 3D  

-  

-   Display the IS values in 3D.

-  

-   There are 4 states for this mode:

-  
    
-   
  • 
-   
    
-    Nothing (i.e. no 3D drawing).
    
-    
  • The "Berries" display, 
-    where each solution point is drawn with a color and a diameter 
-    proportional to its value.
    
-    
  • The 'Potatoes" display, made 
-    from a single, opaque, isosurface 
-    of the IS values.
    
-    
  • The "Onions" display, made 
-    from a serie of nested, transparents, isosurface 
-    of the IS values.
    
-   

-  

-    

-  

-   See an example, on top of a single MRI clipping plane:

-  

-   

-   

-  

-   The "Berries" display is the fastest, and it 
-   gives a good idea of where the sources are.

-  

-   The "Potatoes" display is a little slower, and it 
-   gives an exact 3D isosurface, which can be intersected by 
-   other 3D objects (clipping planes, other windows...). The drawback is 
-   that it only plots the outer surface of the IS, and you can not 
-   differentiate between all these "potatoes" which one is the strongest.

-  

-   The "Onions" display is the slowest one, as it is 
-   indeed a serie of isosurfaces, set with different cutting 
-   values, and drawn transparently. It has the advantage over the 
-   "Potatoes" display that you can see "through" the 
-   first isosurface. So you can tell which "potato" is the 
-   most important, on first sight (see in the examples above, the 
-   potatoes below the clipping plane are not so strong). The 
-   "onions" are also 3D objects that can intersect with others 
-   (clipping planes, other windows...).

-  

-   Show Inverse Solution as 3D vectors  

-  

-   If the results of the IS is vectorial, this will display each of the vectors
-    in 3D.

-  

-   The small sphere stands for the origin of the vector (i.e. the 
-   solution point location of the IS), and the length / width / coloring 
-   of the vector will vary according to the strength of the vector.

-  

-   The usual Brightness / Contrast tuning also 
-   applies here, and you might have to highly increase the brightness, 
-   or to zoom in, if you want to clearly distinguish each vector!

-  

-    

-  

-   See a (zoomed in) example:

-  

-   

-  

-   Show MRI  

-  

-   You can change the way the current MRI is displayed (see here 
-   to change the MRI color and properties).

-  

-   This button is a more convenient way (and faster) to linking
-    the MRI window into the IS one.

-  

-   The modes availables 
-   are exactly the same as the ones from the MRI
-    display.

-  

-    

-  

-   See some examples, with the IS in the 3D 
-   "Potatoes" mode:

-  

-   

-   

-  

-   Show Solution Points  

-  

-   You can add the solution points location in your display.

-  

-   This button is a more convenient way (and faster) to linking
-    the Solution Points window into the IS one.

-  

-   The button cycles between 3 states:

-  
    
-   
  • 
-   
    
-    Nothing (i.e. no Solution Points)
    
-    
  • Small spheres.
    
-    
  • Bigger spheres.
    
-   

-  

-    

-  

-   See an example, with the IS in the 3D 
-   "Potatoes" mode:

-  

-   

-  

-   Regions Of Interest  

-  

-   This button is enabled if a .rois 
-   file is available in the link
-    many file, and the dimension of the rois is equal to the number
-    of solution points.

-  

-   Pressing this button will cycle within all possible rois 
-   listed in the link many file. Once a roi is active, the IS 
-   computation is run as usual, then the results are averaged for each 
-   region at a time. All the solution points of a given region will then 
-   receive the same averaged value, so the display will appear as big 
-   chunks of equal values (this is normal).

-  

-    

-  

-   See an example, without and with rois, while using the Berries
-    display. We can see on the second picture that all the solution 
-   points beloging to a given region have the same value / color!

-  

-   

-  

-   You might be interested to learn how to create
-    the rois file, too?

-  

-   Clipping planes  

-  

-   Set the active clipping planes.

-  

-   See the equivalent MRI 
-   related topic, plus the 2D IS topic,
-    if you want to see the IS on these planes.

-  

-   Slice mode     

-  

-   Switch to a serie of slices, either in the Coronal, Transverse 
-   or Sagittal planes.

-  

-   Visit the equivalent MRI 
-   related topic.

-  

-    

-  

-   See an example:

-  

-   

-  

-   Each view is a serie of 2D intersecting planes, on which the IS is 
-   always drawn in 2D, exactly the same way as here.

-  

-   In each view, the last MRI drawn has a different orientation, as to 
-   figure out where the slices (the grey lines) come from. 
-   Moreover, you can still change the appearance of 
-   this MRI and which IS is drawn on it.

-  

-   You can still rotate 
-   the slices, if the orientation does not suit you...

-  

-   Show Min / Max  

-  

-   Same behavior as the MRI
-    Max feature, except that it works on the Inverse Solution values instead.

-  

-   Note that the Min is only available if the current Inverse 
-   Matrix can produce scalar value results.

-  

-    

-  

-   See an example, either with 2D IS or 3D
-    IS:

-  

-   

-  

-   Find Min / Max positions  

-  

-   Same behavior as the MRI Find Max feature,
-    except that it works on the Inverse Solution values instead.

-  

-   Note that this is independent from displaying 
-   the min / max positions.

-  

-    

-  

-   If both the Min and Max values 
-   are available, they can only be shown at once in the Slice
-    mode display, f.ex.:

-  

-   

-  

-   In all the other displays, the absolute greatest one will be 
-   used to set the clipping plane, f.ex.:

-  

-   

-  

-   You can still shift the clipping planes 
-   by hand, but each 
-   time you will release the mouse, Cartool will go back to the 
-   automatic positionning. This is done on purpose, so you can explore 
-   the other slices to check for some other sweet spots.

-  

-   Brightness  

-  

-   Changing the brightness has a slightly different effect according to 
-   wether you are in a 2D IS or in a 3D
-    IS mode.

-  
    
-   
  • 
-   
    
-    In 2D IS mode, it is similar to the 
-    brightness control of the MRI Brightness.
    
-   
    
-    Here is an example of a low and a high brightness 2D IS:
    
-   
    
-    
    
-   
  • 
-   
    
-    In 3D IS mode, it changes the isosurface 
-    cutting value of the IS, therefore changing the size of the "potatoes".
    
-   
    
-    Here is an example of a low and a high brightness 3D IS:
    
-   
    
-    
    
-   
  • 
-   
    
-    In 3D Vectors mode, it changes the 
-    length / width / brightness of the vectors.
    
-   
    
-    Here is an example of a low and a high brightness 3D 
-    Vectors display:
    
-   
    
-    
    
-   

-  

-   Contrast  

-  

-   Changing the contrast has a slightly different effect according to 
-   wether you are in a 2D IS or in a 3D
-    IS mode.

-  
    
-   
  • 
-   
    
-    In 2D IS mode, it is similar to the 
-    contrast control of the MRI Contrast.
    
-   
    
-    Here is an example of a low and a high contrast 2D IS:
    
-   
    
-    
    
-   
  • 
-   
    
-    In 3D IS mode, it also changes (as for 
-    the brightness) the isosurface 
-    cutting value of the IS, therefore changing the size of the "potatoes".
-     It also changes the color used for the isosurface.
    
-   
    
-    Here is an example of a low and a high contrast 3D IS:
    
-   
    
-    
    
-   

-  

-   Color auto scaling  

-  

-   The color auto scaling has a slightly different effect according to 
-   wether you are in a 2D IS or in a 3D
-    IS mode.

-  
    
-   
  • 
-   
    
-    In 2D IS mode, it is similar to the 
-    contrast control of the MRI Color
-     auto scaling.
    
-   
    
-    Here is an example of auto scaling, with a low and a high 
-    contrast 2D IS:
    
-   
    
-    
    
-   
  • 
-   
    
-    In 3D IS mode, it sets a minimum 
-    visible size for the "potatoes",
-     changing the contrast 
-    finally setting the actual size.
    
-   
    
-    Here is an example of auto scaling, with a low and a high 
-    contrast 3D IS:
    
-   
    
-    
    
-   

-  

-   Color modes  

-  

-   You have 2 series of color modes available, and Cartool 
-   automatically choose the serie according to the type
-    of IS matrix. These matrices being able to produce either signed 
-   or non-signed results.

-  

-   Within the selected serie, you can of course switch between 
-   different color modes (for the Inverse Solutions), similarly to 
-   the Potentials.

-  

-   Reset Regularization  

-  

-   See here.

-  

-   Previous Regularization  

-  

-   See here.

-  

-   Next Regularization  

-  

-   See here.

-  

-   Find optimal Regularization  

-  

-   See here.

-  

-   Switch to another Inverse matrix  

-  

-   The link file can contain more than one 
-   Inverse Solution matrix. This is a very convenient way to 
-   test different models, each model having its own brightness 
-   and contrast values stored.

-  

-   The name of the current IS is written in the top-right part of 
-   the window.

-  

-   Switch to another MRI  

-  

-   The link file will usually contain more 
-   than one MRI file. By cycling between these MRIs you can 
-   focus your message either on the grey matter, the full brain or the 
-   full head.

-  

-   F.ex. the same 3D "onions" IS on 
-   top of two different MRIs (of the same head):

-  

-   

-  

-   Inverse Solutions Display - Mouse

-  

-   See the general mouse actions,
-    and especially the brightness
-    and contrast control and the polling
-    function.

-  

-   Inverse Solutions Display - Menus

-  

-   Edit menu

-  
-  

-   Search menu

-  
    
-   
    
-    Find TF with maximum value
    
-   
      
-    
      
-     Scan all Time Frames, and set the 
-     time cursor to the position where the greatest absolute min or max is.
      
-    
    
-   

-  

-   Regularization menu

-  
    
-   
    
-    Reset Regularization
    
-   
      
-    
      
-     Switch to the first regularization, usually with value 0 (i.e. no regularization).
      
-    
      
-     This function is available only if the Inverse Matrix embeds more
-      than 1 regularization.
      
-    
    
-   
    
-    Previous Regularization
    
-   
      
-    
      
-     Switch to the previous regularization, until the first one is reached.
      
-    
      
-     This function is available only if the Inverse Matrix embeds more
-      than 1 regularization.
      
-    
    
-   
    
-    Next Regularization
    
-   
      
-    
      
-     Switch to the next regularization, until the last one is reached.
      
-    
      
-     This function is available only if the Inverse Matrix embeds more
-      than 1 regularization.
      
-    
    
-   
    
-    Find optimal Regularization, at 
-    current time range only
    
-   
      
-    
      
-     Looking for the optimal regularization at the current time selection 
-     (see below).
      
-    
      
-     This option allows you to have the regularization parameter to be as 
-     precise as possible at a given time frame (or time interval). As the 
-     obtained value depends on the noise level at the current time range, 
-     this regularization might not in turn be optimal for other parts of 
-     the data. In that case, either repeat the regularization search, or 
-     try to have a global, fixed regularization value for the whole data, 
-     as explained below.
      
-    
    
-   
    
-    Find optimal Regularization, 
-    across whole time range
    
-   
      
-    
      
-     Looking for the optimal regularization for the whole data set, 
-     independently of the current time selection.
      
-    
      
-     This option allows you to compute a single regularization parameter 
-     for the whole data. You can therefore use this value to export
-      the inverse results, f.ex. If you think you're missing some 
-     precisions somewhere, you can try to compute a specific 
-     regularization value for a given time range, as explained above.
      
-    
    
-   
    
-     
    
-   
      
-    
      
-     In either two cases, the time range considered (current or whole) is 
-     scanned and a best regularization is computed for each time frame.
-      Then the average of all the obtained regularizations is computed.
      
-    
      
-     The best regularization at a given time frame is found by plotting 
-     the average norm of all solution points as a function of 
-     regularization, and then taking the L-corner of this curve 
-     (f.ex. here regularization 3):
      
-    
      
-     
      
-    
      
-     Important:
      
-    
        
-     
      • 
-     
        
-      The computed regularization is usually a good hint, but you 
-      still have to be critical of this value. Watch the result, and 
-      try the previous and next regularizations f.ex.
        
-     
      • 
-     
        
-      The proposed value is also dependent of the type of inverse solution,
-       f.ex. a LORETA vs a WMN, though it shouldn't vary that much for a 
-      given set of data.
      
-      
      
-     This function is available only if the Inverse Matrix embeds more
-      than 1 regularization.
      
-    
    
-   

-  

-   Options menu

-  
    
-   
    
-    Specify a display scaling
    
-   
      
-    
      
-     Ask the user for an arbitrary scaling value, equivalent to setting 
-     the brightness.
      
-    
    
-   
    
-    Show / hide color scaling
    
-   
      
-    
      
-     Does what it says.
      
-    
    
-   
    
-    Show / hide orientation
    
-   
      
-    
      
-     Does what it says.
      
-    
    
-   
    
-    Averaging precedence of inverse
    
-   
      
-    
      
-     Before:
      
-    
        
-     
        
-      The EEG is first averaged for the current time period selected, then 
-      the Inverse Solution of this mean period taken
        
-      = InverseSolution ( Mean EEG ( for each time point ) )
        
-     
      
-    
      
-     After:
      
-    
        
-     
        
-      The Inverse Solution is computed sequentially for each time point of 
-      the current time period selected. Then the average of these IS is taken
        
-      = Mean ( InverseSolution ( for each time point ) )
        
-     
      
-    
    
-   
    
-    'Depth shifting' trick for 3D inverse
    
-   
      
-    
      
-     This is discussed in the MRI
-      Depth Shifting topic and in the Potential
-      topic.
      
-    
      
-     Be aware that the shift only applies to the 3D 
-     Inverse Solutions, and neither to the 2D 
-     Inverse Solutions nor the MRI itself.
      
-    
      
-     See an example here, first picture is a clipped MRI and an IS without 
-     depth shifting. Second picture the MRI is not clipped and the IS are 
-     "depth shifted" on top. Note that in the latter case, you 
-     can see a little more detailed IS:
      
-    
      
-     
      
-    
    
-   

-  

-   Inverse Solutions Display - Technical points

-  

-   How do I get this display?

-  

-   This display is actually automatically generated when enough 
-   files have been linked together,
-    and therefore share enough informations.

-  

-   There are two cases concerning the files:

-  

-   First case:

-  
-  

-    

-  

-   Cartool will multiply the IS matrix with each time frames of each EEG 
-   files, in real-time.

-  

-   Second case:

-  
    
-   
  • 
-   
    
-    1 (or more) RIS file(s),
    
-   
  • 
-   
    
-    One solution points file.
    
-   
  • 
-   
    
-    At least one MRI file, 
-    containing a mask around the Grey matter;
    
-   
    
-    other MRIs with the Brain or Full Head are optionals, though they do 
-    improve the display quality.
    
-   

-  

-    

-  

-   The multiplication of the IS matrix and the EEG data has been done 
-   somewhere else (f.ex. with the File
-    Calculator), and the result is stored in a RIS file. 
-   This is usually faster to work with, but it lacks suppleness, as the 
-   data are computed once for all.

-  

-   It can be very useful, though, if you want to compute the inverse 
-   solutions with your own recipe.

-  

-   Important points:

-  
    
-   
  • 
-   
    
-    Putting many EEG / RIS files will show as many inverse windows 
-    as there are of files.
    
-   
  • 
-   
    
-    Only one solution points file is allowed, and it has to be 
-    absolutely the same one that has been used to build the IS matrix 
-    you want to use. Missing this point will produce totally wrong displays.
-     Only the one who actually built the IS matrix can certify which file 
-    has been used.
    
-   
  • 
-   
    
-    You can put many IS matrices, but only one is active at a time. You 
-    can of course toggle between these matrices, 
-    so you can compare between different models.
    
-   
  • 
-   
    
-    You have to put at least 1 MRI, 
-    though 2 or 3 should be the usual case. The first one 
-    is mandatory, it holds a mask 
-    where non-zero values voxels specifies the grey-matter, and therefore 
-    where the IS will be actually computed 
-    and displayed.
    
-   
  • 
-   
    
-    The following MRIs can contain, for example, a segmented brain and a 
-    full head, so you can display the inverse solution in these spaces. 
-    Each of these MRIs must of course be co-registered.
    
-   
  • 
-   
    
-    All the MRIs must match exactly the Solution Points geometry.
    
-   
  • 
-   
    
-    You can also mix the two cases for linkings, that is, both EEG files 
-    with IS matrices and pre-computed RIS files.
    
-   
  • 
-   
    
-    Cartool is doing a lot of checkings to ensure you are on the safe 
-    side of this elaborated display. Though, only you can really assert 
-    that all these files finally match together (the solution points with 
-    the MRI space and the IS matrix).
    
-   

-  

-    

-  

-   Recommended readings: the fabulous Linking
-    Files story, and the ignominous "Windows
-    in Slavery" tale.

-  

-   How do I compute Inverse Solutions matrices?

-  

-   Either from the Cartool toolbox,
-    or from third-party applications.

-  

-   Matrix results: scalar or vectorial

-  

-   According to the model underneath the IS 
-   matrix you are using, the results at each solution points 
-   location can either be some signed scalar values, or vectors 
-   (direction plus intensity of the source). This is wired into the 
-   matrix and can not be changed by Cartool!

-  

-   It has the following consequences:

-  
    
-   
  • 
-   
    
-    Color maps will account for the possible 
-    signed values.
    
-   
  • 
-   
    
-    If results are signed scalar values, Cartool will produce two isosurfaces 
-    for the 3D IS, one for the positive values 
-    alone, and the other one for the negative values alone. Each one will 
-    be colored differently, of course.
    
-   
  • 
-   
    
-    If the results are vectors, Cartool currently only display the value 
-    of their norms (aka intensity). This is related to the averaging
-     precedence topic.
    
-   

-  

-   Time Averaging  

-  

-   This is the same as the basic Time
-    Averaging.

-  

-   Note however the potential effect of changing the Averaging
-    precedence, which can lead to different results.

-  

-   Time Sequence  

-  

-   This is the same as the basic Time
-    Sequence.

-  

-   See a few typical examples here, with the relevant parameters also specified:

-  

-    

-  
-  

-    

-  

-   Time Animation  

-  

-   This is the same as the basic Time
-    Animation.

-  

-   At the moment, the smoother animation will be by using the highly 
-   optimized Slice Mode!

-  

-   Combining 2D IS and 3D IS

-  

-   This is a possible, but not very useful, combination. That is why 
-   most of the time, unless you really want it, Cartool makes 2D and 3D 
-   IS exclusive (you can still force them together, though).

-  

-   The 2D IS applies only on the clipping
-    planes or the slices, so it is more 
-   restricted view than the 3D IS. When you turn 
-   on the 3D IS, then the 2D IS is switched off, because it does not 
-   bring more informations, and increase the display time. However you 
-   can bring it back by clicking again on the 2D IS button,
-    which gives you both the planar and the 3D IS:

-  

-   

-  

-   Finally, also note that switching off the 3D IS will re-activate the 
-   2D IS back.

-  

-    

-  

-   Changing the color of the MRI

-  

-   All the color options within the IS 
-   display only apply to the Inverse Solutions themselves.

-  

-   Changing the MRI coloring (changing the 
-   brightness, or the color mode f.ex.) is done very simply by switching
-    to the related MRI window,
-    and do your changes there. The results are shown in real-time, so 
-   you can easily tune your IS display:

-  

-   

-  

-   A good hint: if you want only to change the brightness
-    / contrast of the MRI, you don't even need to make the window 
-   active ("clicking" on it). It is enough to use the right-click 
-   above the MRI window.

-  

-    

-  

-   Interpolating between solution points

-  

-   The Solution Points 
-   are actually a sub-sampling of the brain grey
-    matter. To fill the spaces between the SPs, some kind of 
-   interpolation is therefore needed.

-  

-   A 4 Nearest Neighbors (4NN) method is used, 
-   due to its nice visual output.

-  

-   Note that the interpolation is restricted to the content
-    of the grey mask.

-  

-   

-  

-     

-  

-   Solution points distribution

-  

-   The solution points, according to 
-   which IS model is used, can either be 
-   placed with a regular interval spacing, or arbitrarily distributed 
-   among the grey matter voxels.

-  

-   In fact, you shouldn't care that much about this, Cartool does it 
-   best to handle both cases. However, in case of non-regular 
-   solution points, the 3D IS isosurface rendering 
-   is noticeably slower, because it is computed in the full grey 
-   matter space. The regular grid case, on the other hand, use this 
-   property to compute the isosurface on a downsampled version of the 
-   grey matter MRI.

-  

-   See an example of regularly and non-regularly distributed solution 
-   points (this is not a perspective distortion):

-  

-   

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    
+ 
+     

+         

+             Inverse Solutions Display
+         

+         

+              
+         

+         

+             If you don't know how to get this display on the first hand, please 
+                 read
+                 this topic first
+             . Also note that very often Inverse Solutions
+             will be nicknamed IS.
+         

+         

+             You can 
+                 
+                     compute the inverse
+                     matrices here
+                 
+             , or 
+                 
+                     compute the
+                     results of inverse solutions
+                 
+             from EEG (or frequency) files.
+         

+         

+             Buttons
+         

+         

+               
+         

+         

+               
+         

+         

+             Display modes:
+         

+         

+              
+         

+         

+             
+         

+         

+             
+         

+         

+                
+         

+         

+              
+         

+         

+                
+         

+         

+             
+         

+         

+             
+         

+         

+             Mouse
+         

+         

+             Menus
+         

+         

+             Edit
+         

+         
+         

+             Search
+         

+         
+         

+             Regularization
+         

+         
+         

+             Options
+         

+         
+         

+             Technical points
+         

+         

+             How do I get this display?

+             How do I compute the Inverse Solutions matrices?

+             Matrix results: scalar of vectorial

+             Time Averaging
Time Sequence

+             Time Animation
Combining 2D IS and 3D IS

+             Changing the color of the MRI

+             Interpolating between solution points

+             Solution points distribution
+         

+         

+             Inverse Solutions Display - Buttons
+         

+         

+             Display modes
+         

+         

+               
+         

+         

+             Your display will depend mainly on these 5 buttons. Most of
+             the time their effects combine together to provide some rich
+             output, so knowing their roles is fundamental to get the most of this display!
+         

+         

+             Show Inverse Solution on 2D clipping
+             planes  
+         

+         

+             The 
+                 IS will be drawn in 2D (flat) on the current 
+                     clipping
+                     planes
+                 
+             , the values seen are the ones intersecting those planes.
+         

+         

+             The button cycles between 3 states:
+         

+         
    
+             
  • 
+                 
    
+                     Nothing (i.e. no 2D drawing)
    
+             
  • Drawing with transparency for the lowest values
    
+             
  • Opaque drawing.
    
+         

+         

+              
+         

+         

+             See an example, on top of a single MRI clipping plane
+             (you can set all 3 planes if you wish):
+         

+         

+             
+         

+         

+             Be aware that if no clipping planes are set, there will
+             be nothing to see!
+         

+         

+             However, 
+                 you can have a clipping plane selected
+                 without any MRI rendering
+             . This will draw
+             only the IS, as f.ex.:
+         

+         

+             
+         

+         

+             Finally, note that the coloring only occurs where the 
+                 MRI
+                 mask provided has non-null values
+             .
+         

+         

+             Show Inverse Solution in 3D  
+         

+         

+             Display the IS values in 3D.
+         

+         

+             There are 4 states for this mode:
+         

+         
    
+             
  • 
+                 
    
+                     Nothing (i.e. no 3D drawing).
    
+             
  • 
+                 The "Berries" display,
+                 where each 
+                     solution point is drawn with a color and a diameter
+                     proportional to its value
+                 .
    
+             
  • 
+                 The 'Potatoes" display, made
+                 from a single, opaque, isosurface
+                 of the IS values.
    
+             
  • 
+                 The "Onions" display, made
+                 from a serie of nested, transparents, isosurface
+                 of the IS values.
    
+         

+         

+              
+         

+         

+             See an example, on top of a single MRI clipping plane:
+         

+         

+             

+             
+         

+         

+             The "Berries" display is the fastest, and it
+             gives a good idea of where the sources are.
+         

+         

+             The "Potatoes" display is a little slower, and it
+             gives an exact 3D isosurface, which can be intersected by
+             other 3D objects (clipping planes, other windows...). The drawback is
+             that it only plots the outer surface of the IS, and you can not
+             differentiate between all these "potatoes" which one is the strongest.
+         

+         

+             The "Onions" display is the slowest one, as it is
+             indeed a serie of isosurfaces, set with different cutting
+             values, and drawn transparently. It has the advantage over the
+             "Potatoes" display that you can see "through" the
+             first isosurface. So you can tell which "potato" is the
+             most important, on first sight (see in the examples above, the
+             potatoes below the clipping plane are not so strong). The
+             "onions" are also 3D objects that can intersect with others
+             (clipping planes, other windows...).
+         

+         

+             Show Inverse Solution as 3D vectors  
+         

+         

+             If the results of the IS is vectorial, this will display each of the 
+                 vectors
+                 in 3D
+             .
+         

+         

+             The small sphere stands for the origin of the vector (i.e. the
+             solution point location of the IS), and the length / width / coloring
+             of the vector will vary according to the strength of the vector.
+         

+         

+             The usual Brightness / Contrast tuning also
+             applies here, and you might have to highly increase the brightness,
+             or to zoom in, if you want to clearly distinguish each vector!
+         

+         

+              
+         

+         

+             See a (zoomed in) example:
+         

+         

+             
+         

+         

+             Show MRI  
+         

+         

+             You can change the way the current MRI is displayed (see here
+             to change the MRI color and properties).
+         

+         

+             This button is a more convenient way (and faster) to 
+                 
+                     linking
+                     the MRI window
+                 
+              into the IS one.
+         

+         

+             The modes availables
+             are exactly the same as the ones from the 
+                 MRI
+                 display
+             .
+         

+         

+              
+         

+         

+             See some examples, with the 
+                 IS in the 3D
+                 "Potatoes" mode
+             :
+         

+         

+             

+             
+         

+         

+             Show Solution Points  
+         

+         

+             You can add the solution points location in your display.
+         

+         

+             This button is a more convenient way (and faster) to 
+                 linking
+                 the Solution Points window
+              into the IS one.
+         

+         

+             The button cycles between 3 states:
+         

+         
    
+             
  • 
+                 
    
+                     Nothing (i.e. no Solution Points)
    
+             
  • Small spheres.
    
+             
  • Bigger spheres.
    
+         

+         

+              
+         

+         

+             See an example, with the 
+                 IS in the 3D
+                 "Potatoes" mode
+             :
+         

+         

+             
+         

+         

+             Regions Of Interest  
+         

+         

+             This button is enabled if a .rois
+             file is available in the 
+                 link
+                 many file
+             , and the dimension of the rois is equal to the 
+                 number
+                 of solution points
+             .
+         

+         

+             Pressing this button will cycle within all possible rois
+             listed in the link many file. Once a roi is active, the IS
+             computation is run as usual, then the results are averaged for each
+             region at a time. All the solution points of a given region will then
+             receive the same averaged value, so the display will appear as big
+             chunks of equal values (this is normal).
+         

+         

+              
+         

+         

+             See an example, without and with rois, while using the 
+                 Berries
+                 display
+             . We can see on the second picture that all the solution
+             points beloging to a given region have the same value / color!
+         

+         

+             
+         

+         

+             You might be interested to learn how to 
+                 create
+                 the rois file
+             , too?
+         

+         

+             Clipping planes  
+         

+         

+             Set the active clipping planes.
+         

+         

+             See the equivalent 
+                 
+                     MRI
+                     related topic
+                 
+             , plus the 2D IS topic,
+             if you want to see the IS on these planes.
+         

+         

+             Slice mode     
+         

+         

+             Switch to a serie of slices, either in the Coronal, Transverse
+             or Sagittal planes.
+         

+         

+             Visit the equivalent 
+                 
+                     MRI
+                     related topic
+                 
+             .
+         

+         

+              
+         

+         

+             See an example:
+         

+         

+             
+         

+         

+             Each view is a serie of 2D intersecting planes, on which the 
+                 IS is
+                 always drawn in 2D
+             , exactly the same way as here.
+         

+         

+             In each view, the last MRI drawn has a different orientation, as to
+             figure out where the slices (the grey lines) come from.
+             Moreover, you can still change the 
+                 appearance of
+                 this MRI
+              and which IS is drawn on it.
+         

+         

+             You can still rotate
+             the slices, if the orientation does not suit you...
+         

+         

+             Show Min / Max  
+         

+         

+             Same behavior as the 
+                 
+                     MRI
+                     Max feature
+                 
+             , except that it works on the Inverse Solution values instead.
+         

+         

+             Note that the Min is only available if the current Inverse
+             Matrix can produce scalar value results.
+         

+         

+              
+         

+         

+             See an example, either with 2D IS or 
+                 3D
+                 IS
+             :
+         

+         

+             
+         

+         

+             Find Min / Max positions  
+         

+         

+             Same behavior as the MRI Find Max feature,
+             except that it works on the Inverse Solution values instead.
+         

+         

+             Note that this is independent from 
+                 displaying
+                 the min / max positions.
+             
+         

+         

+              
+         

+         

+             If both the Min and Max values
+             are available, they can only be shown at once in the 
+                 Slice
+                 mode display
+             , f.ex.:
+         

+         

+             
+         

+         

+             In all the other displays, the absolute greatest one will be
+             used to set the clipping plane, f.ex.:
+         

+         

+             
+         

+         

+             You can still shift the clipping planes
+             by hand, but each
+             time you will release the mouse, Cartool will go back to the
+             automatic positionning. This is done on purpose, so you can explore
+             the other slices to check for some other sweet spots.
+         

+         

+             Brightness  
+         

+         

+             Changing the brightness has a slightly different effect according to
+             wether you are in a 2D IS or in a 
+                 
+                     3D
+                     IS
+                 
+              mode.
+         

+         
    
+             
  • 
+                 
    
+                     In 2D IS mode, it is similar to the
+                     brightness control of the MRI Brightness.
+                 
    
+                 
    
+                     Here is an example of a low and a high brightness 2D IS:
+                 
    
+                 
    
+                     
+                 
    
+             
  • 
+                 
    
+                     In 3D IS mode, it changes the isosurface
+                     cutting value of the IS, therefore changing the size of the "potatoes".
+                 
    
+                 
    
+                     Here is an example of a low and a high brightness 3D IS:
+                 
    
+                 
    
+                     
+                 
    
+             
  • 
+                 
    
+                     In 3D Vectors mode, it changes the
+                     length / width / brightness of the vectors.
+                 
    
+                 
    
+                     Here is an example of a low and a high brightness 3D
+                     Vectors display:
+                 
    
+                 
    
+                     
+                 
    
+         

+         

+             Contrast  
+         

+         

+             Changing the contrast has a slightly different effect according to
+             wether you are in a 2D IS or in a 
+                 
+                     3D
+                     IS
+                 
+              mode.
+         

+         
    
+             
  • 
+                 
    
+                     In 2D IS mode, it is similar to the
+                     contrast control of the MRI Contrast.
+                 
    
+                 
    
+                     Here is an example of a low and a high contrast 2D IS:
+                 
    
+                 
    
+                     
+                 
    
+             
  • 
+                 
    
+                     In 3D IS mode, it also changes (as for
+                     the brightness) the isosurface
+                     cutting value of the IS, therefore changing the size of the "potatoes".
+                     It also changes the color used for the isosurface.
+                 
    
+                 
    
+                     Here is an example of a low and a high contrast 3D IS:
+                 
    
+                 
    
+                     
+                 
    
+         

+         

+             Color auto scaling  
+         

+         

+             The color auto scaling has a slightly different effect according to
+             wether you are in a 2D IS or in a 
+                 
+                     3D
+                     IS
+                 
+              mode.
+         

+         
    
+             
  • 
+                 
    
+                     In 2D IS mode, it is similar to the
+                     contrast control of the MRI 
+                         Color
+                         auto scaling
+                     .
+                 
    
+                 
    
+                     Here is an example of auto scaling, with a low and a high
+                     contrast 2D IS:
+                 
    
+                 
    
+                     
+                 
    
+             
  • 
+                 
    
+                     In 3D IS mode, it sets a 
+                         minimum
+                         visible size
+                      for the "potatoes",
+                     changing the contrast
+                         finally setting the actual size
+                     .
+                 
    
+                 
    
+                     Here is an example of auto scaling, with a low and a high
+                     contrast 3D IS:
+                 
    
+                 
    
+                     
+                 
    
+         

+         

+             Color modes  
+         

+         

+             You have 2 series of color modes available, and Cartool
+             automatically choose the serie according to the 
+                 type
+                 of IS matrix
+             . These matrices being able to produce either signed
+             or non-signed results.
+         

+         

+             Within the selected serie, you can of course 
+                 switch between
+                 different color modes
+              (for the Inverse Solutions), similarly to
+             the Potentials.
+         

+         

+             Reset Regularization  
+         

+         

+             See here.
+         

+         

+             Previous Regularization  
+         

+         

+             See here.
+         

+         

+             Next Regularization  
+         

+         

+             See here.
+         

+         

+             Find optimal Regularization  
+         

+         

+             See here.
+         

+         

+             Switch to another Inverse matrix  
+         

+         

+             The link file can contain 
+                 
+                     more than one
+                     Inverse Solution matrix
+                 
+             . This is a very convenient way to
+             test different models, each model having its own brightness
+             and contrast values stored.
+         

+         

+             The name of the current IS is written in the top-right part of
+             the window.
+         

+         

+             Switch to another MRI  
+         

+         

+             The link file will usually contain 
+                 
+                     more
+                     than one MRI file
+                 
+             . By cycling between these MRIs you can
+             focus your message either on the grey matter, the full brain or the
+             full head.
+         

+         

+             F.ex. the same 3D "onions" IS on
+             top of two different MRIs (of the same head):
+         

+         

+             
+         

+         

+             Inverse Solutions Display - Mouse
+         

+         

+             See the general mouse actions,
+             and especially the 
+                 brightness
+                 and contrast control
+              and the 
+                 polling
+                 function
+             .
+         

+         

+             Inverse Solutions Display - Menus
+         

+         

+             Edit menu
+         

+         
+         

+             Search menu
+         

+         
    
+             
    
+                 Find TF with maximum value
+             
    
+             
      
+                 
      
+                     Scan all Time Frames, and set the
+                     time cursor to the position where the greatest absolute min or max is.
+                 
      
+             
    
+         

+         

+             Regularization menu
+         

+         
    
+             
    
+                 Reset Regularization
+             
    
+             
      
+                 
      
+                     Switch to the first regularization, usually with value 0 (i.e. no regularization).
+                 
      
+                 
      
+                     This function is available only if the Inverse Matrix embeds 
+                         more
+                         than 1 regularization
+                     .
+                 
      
+             
    
+             
    
+                 Previous Regularization
+             
    
+             
      
+                 
      
+                     Switch to the previous regularization, until the first one is reached.
+                 
      
+                 
      
+                     This function is available only if the Inverse Matrix embeds 
+                         more
+                         than 1 regularization
+                     .
+                 
      
+             
    
+             
    
+                 Next Regularization
+             
    
+             
      
+                 
      
+                     Switch to the next regularization, until the last one is reached.
+                 
      
+                 
      
+                     This function is available only if the Inverse Matrix embeds 
+                         more
+                         than 1 regularization
+                     .
+                 
      
+             
    
+             
    
+                 
+                     Find optimal Regularization, at
+                     current time range only
+                 
+             
    
+             
      
+                 
      
+                     Looking for the optimal regularization at the current time selection
+                     (see below).
+                 
      
+                 
      
+                     This option allows you to have the regularization parameter to be as
+                     precise as possible at a given time frame (or time interval). As the
+                     obtained value depends on the noise level at the current time range,
+                     this regularization might not in turn be optimal for other parts of
+                     the data. In that case, either repeat the regularization search, or
+                     try to have a global, fixed regularization value for the whole data,
+                     as explained below.
+                 
      
+             
    
+             
    
+                 
+                     Find optimal Regularization,
+                     across whole time range
+                 
+             
    
+             
      
+                 
      
+                     Looking for the optimal regularization for the whole data set,
+                     independently of the current time selection.
+                 
      
+                 
      
+                     This option allows you to compute a single regularization parameter
+                     for the whole data. You can therefore use this value to 
+                         export
+                         the inverse results
+                     , f.ex. If you think you're missing some
+                     precisions somewhere, you can try to compute a specific
+                     regularization value for a given time range, as explained above.
+                 
      
+             
    
+             
    
+                  
+             
    
+             
      
+                 
      
+                     In either two cases, the time range considered (current or whole) is
+                     scanned and a best regularization is computed for each time frame.
+                     Then the average of all the obtained regularizations is computed.
+                 
      
+                 
      
+                     The best regularization at a given time frame is found by plotting
+                     the average norm of all solution points as a function of
+                     regularization, and then taking the L-corner of this curve
+                     (f.ex. here regularization 3):
+                 
      
+                 
      
+                     
+                 
      
+                 
      
+                     Important:
+                 
      
+                 
        
+                     
      • 
+                         
        
+                             The computed regularization is usually a good hint, but you
+                             still have to be critical of this value. Watch the result, and
+                             try the previous and next regularizations f.ex.
+                         
        
+                     
      • 
+                         
        
+                             The proposed value is also dependent of the type of inverse solution,
+                             f.ex. a LORETA vs a WMN, though it shouldn't vary that much for a
+                             given set of data.
+                 
      
+                  
+                 
      
+                 This function is available only if the Inverse Matrix embeds
+                 
+                     more
+                     than 1 regularization
+                 .
      
+             
    
+         

+         

+             Options menu
+         

+         
    
+             
    
+                 Specify a display scaling
+             
    
+             
      
+                 
      
+                     Ask the user for an arbitrary scaling value, equivalent to setting
+                     the brightness.
+                 
      
+             
    
+             
    
+                 Show / hide color scaling
+             
    
+             
      
+                 
      
+                     Does what it says.
+                 
      
+             
    
+             
    
+                 Show / hide orientation
+             
    
+             
      
+                 
      
+                     Does what it says.
+                 
      
+             
    
+             
    
+                 Averaging precedence of inverse
+             
    
+             
      
+                 
      
+                     Before:
+                 
      
+                 
        
+                     
        
+                         The EEG is first averaged for the current time period selected, then
+                         the Inverse Solution of this mean period taken
        
+                         = InverseSolution ( Mean EEG ( for each time point ) )
+                     
        
+                 
      
+                 
      
+                     After:
+                 
      
+                 
        
+                     
        
+                         The Inverse Solution is computed sequentially for each time point of
+                         the current time period selected. Then the average of these IS is taken
        
+                         = Mean ( InverseSolution ( for each time point ) )
+                     
        
+                 
      
+             
    
+             
    
+                 'Depth shifting' trick for 3D inverse
+             
    
+             
+         

+         

+             Inverse Solutions Display - Technical points
+         

+         

+             How do I get this display?
+         

+         

+             This display is actually automatically generated when enough
+             files have been linked together,
+             and therefore share enough informations.
+         

+         

+             There are two cases concerning the files:
+         

+         

+             First case:
+         

+         
+         

+              
+         

+         

+             Cartool will multiply the IS matrix with each time frames of each EEG
+             files, in real-time.
+         

+         

+             Second case:
+         

+         
    
+             
  • 
+                 
    
+                     1 (or more) RIS file(s),
+                 
    
+             
  • 
+                 
    
+                     One solution points file.
+                 
    
+             
  • 
+                 
    
+                     At least one MRI file,
+                     containing a mask around the Grey matter;
+                 
    
+                 
    
+                     other MRIs with the Brain or Full Head are optionals, though they do
+                     improve the display quality.
+                 
    
+         

+         

+              
+         

+         

+             The 
+                 multiplication of the IS matrix and the EEG data has been done
+                 somewhere else
+              (f.ex. with the 
+                 
+                     File
+                     Calculator
+                 
+             ), and the result is stored in a RIS file.
+             This is usually faster to work with, but it lacks suppleness, as the
+             data are computed once for all.
+         

+         

+             It can be very useful, though, if you want to compute the inverse
+             solutions with your own recipe.
+         

+         

+             Important points:
+         

+         
    
+             
  • 
+                 
    
+                     Putting many EEG / RIS files will show as many inverse windows
+                     as there are of files.
+                 
    
+             
  • 
+                 
    
+                     Only one solution points file is allowed, and 
+                         it has to be
+                         absolutely the same one that has been used to build the IS matrix
+                     
+                     you want to use. Missing this point will produce totally wrong displays.
+                     Only the one who actually built the IS matrix can certify which file
+                     has been used.
+                 
    
+             
  • 
+                 
    
+                     You can put many IS matrices, but only one is active at a time. You
+                     can of course toggle between these matrices,
+                     so you can compare between different models.
+                 
    
+             
  • 
+                 
    
+                     You have to put at least 1 MRI,
+                     though 2 or 3 should be the usual case. The first one
+                     is mandatory, it holds a mask
+                     where non-zero values voxels specifies the grey-matter, and therefore
+                     where the IS will be actually 
+                         computed
+                         and displayed
+                     .
+                 
    
+             
  • 
+                 
    
+                     The following MRIs can contain, for example, a segmented brain and a
+                     full head, so you can display the inverse solution in these spaces.
+                     Each of these MRIs must of course be co-registered.
+                 
    
+             
  • 
+                 
    
+                     All the MRIs must match exactly the Solution Points geometry.
+                 
    
+             
  • 
+                 
    
+                     You can also mix the two cases for linkings, that is, both EEG files
+                     with IS matrices and pre-computed RIS files.
+                 
    
+             
  • 
+                 
    
+                     Cartool is doing a lot of checkings to ensure you are on the safe
+                     side of this elaborated display. Though, only you can really assert
+                     that all these files finally match together (the solution points with
+                     the MRI space and the IS matrix).
+                 
    
+         

+         

+              
+         

+         

+             Recommended readings: the fabulous 
+                 
+                     Linking
+                     Files
+                 
+              story, and the ignominous "
+                 
+                     Windows
+                     in Slavery
+                 
+             " tale.
+         

+         

+             How do I compute Inverse Solutions matrices?
+         

+         

+             Either from the Cartool toolbox,
+             or from third-party applications.
+         

+         

+             Matrix results: scalar or vectorial
+         

+         

+             According to the model underneath the 
+                 IS
+                 matrix you are using
+             , the results at each solution points
+             location can either be some signed scalar values, or vectors
+             (direction plus intensity of the source). This is wired into the
+             matrix and can not be changed by Cartool!
+         

+         

+             It has the following consequences:
+         

+         
    
+             
  • 
+                 
    
+                     Color maps will account for the possible
+                     signed values.
+                 
    
+             
  • 
+                 
    
+                     If results are signed scalar values, Cartool will produce two isosurfaces
+                     for the 3D IS, one for the positive values
+                     alone, and the other one for the negative values alone. Each one will
+                     be colored differently, of course.
+                 
    
+             
  • 
+                 
    
+                     If the results are vectors, Cartool currently only display the value
+                     of their norms (aka intensity). This is related to the 
+                         averaging
+                         precedence
+                      topic.
+                 
    
+         

+         

+             Time Averaging  
+         

+         

+             This is the same as the basic 
+                 Time
+                 Averaging
+             .
+         

+         

+             Note however the potential effect of changing the 
+                 
+                     Averaging
+                     precedence
+                 
+             , which can lead to different results.
+         

+         

+             Time Sequence  
+         

+         

+             This is the same as the basic 
+                 Time
+                 Sequence
+             .
+         

+         

+             See a few typical examples here, with the relevant parameters also specified:
+         

+         

+              
+         

+         
+         

+              
+         

+         

+             Time Animation  
+         

+         

+             This is the same as the basic 
+                 Time
+                 Animation
+             .
+         

+         

+             At the moment, the smoother animation will be by using the highly
+             optimized Slice Mode!
+         

+         

+             Combining 2D IS and 3D IS
+         

+         

+             This is a possible, but not very useful, combination. That is why
+             most of the time, unless you really want it, Cartool makes 2D and 3D
+             IS exclusive (you can still force them together, though).
+         

+         

+             The 2D IS applies only on the 
+                 clipping
+                 planes
+              or the slices, so it is more
+             restricted view than the 3D IS. When you turn
+             on the 3D IS, then the 2D IS is switched off, because it does not
+             bring more informations, and increase the display time. However you
+             can bring it back by clicking again on the 2D IS button,
+             which gives you both the planar and the 3D IS:
+         

+         

+             
+         

+         

+             Finally, also note that switching off the 3D IS will re-activate the
+             2D IS back.
+         

+         

+              
+         

+         

+             Changing the color of the MRI
+         

+         

+             All the color options within the IS
+             display only apply to the Inverse Solutions themselves.
+         

+         

+             Changing the MRI coloring (changing the
+             brightness, or the color mode f.ex.) is done very simply by 
+                 switching
+                 to the related
+             MRI window,
+             and do your changes there. The results are shown in real-time, so
+             you can easily tune your IS display:
+         

+         

+             
+         

+         

+             A good hint: if you want only to change the 
+                 brightness
+                 / contrast of the MRI
+             , you don't even need to make the window
+             active ("clicking" on it). It is enough to 
+                 use the right-click
+                 above the MRI window
+             .
+         

+         

+              
+         

+         

+             Interpolating between solution points
+         

+         

+             The Solution Points
+             are actually a sub-sampling of the brain 
+                 grey
+                 matter
+             . To fill the spaces between the SPs, some kind of
+             interpolation is therefore needed.
+         

+         

+             A 4 Nearest Neighbors (4NN) method is used,
+             due to its nice visual output.
+         

+         

+             Note that the interpolation is restricted to the 
+                 
+                     content
+                     of the grey mask
+                 .
+             
+         

+         

+             
+         

+         

+               
+         

+         

+             Solution points distribution
+         

+         

+             The solution points, according to
+             which IS model is used, can either be
+             placed with a regular interval spacing, or arbitrarily distributed
+             among the grey matter voxels.
+         

+         

+             In fact, you shouldn't care that much about this, Cartool does it
+             best to handle both cases. However, in case of 
+                 non-regular
+                 solution points
+             , the 3D IS isosurface rendering
+             is noticeably slower, because it is computed in the full grey
+             matter space. The regular grid case, on the other hand, use this
+             property to compute the isosurface on a 
+                 downsampled version of the
+                 grey matter MRI
+             .
+         

+         

+             See an example of regularly and non-regularly distributed solution
+             points (this is not a perspective distortion):
+         

+         

+             
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+     

  
 
\ No newline at end of file
diff --git a/docs/ReferenceGuide/file-calculator.html b/docs/ReferenceGuide/file-calculator.html
index 18c2d59c..d179a2a7 100644
--- a/docs/ReferenceGuide/file-calculator.html
+++ b/docs/ReferenceGuide/file-calculator.html
@@ -18,1109 +18,1408 @@
 }
 
  
- 
-  

-   File Calculator

-  

-    

-  

-   What is the File Calculator?
How to run the File Calculator

-   Expressions

-  
-  

-   Results of Inverse Solution

-   Results
Technical points and hints

-  

-   What is the File Calculator?

-  

-   This is a tool to batch-process sets of files with a mathematical
-    expression of your liking. There can be many sets of files to 
-   use, but each set should be somehow a coherent one, f.ex. all the 
-   files of all subjects for one condition. Expressions are composed 
-   with elementary operations, see below.

-  

-   How to run the File Calculator

-  

-   Call the dialog from Tools
-    | File Calculator menu.

-  

-   The following dialog pops out. Fill the parameters which are relevant 
-   for you, drop the sets of files to process, then click either 
-   on the Process button:

-  

-   

-    

-   

-  

-   

-    
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-    

-       

-        Groups of Files

-       

-        You can Drag & Drop files here.

-       

-        Add New Group of Files

-       

-        Enter a new group of files.

-       

-        See this note about groups.

-       

-        Remove Last Group

-       

-        Does what it says (amazing).

-       

-        Clear All Groups

-       

-        Clear out all the groups at once.

-       

-        Read Lists from File

-       

-        You can direclty retrieve the lists of groups previously saved.

-       

-        Write Lists to File

-       

-        You can save the lists of current groups into a file, in case you 
-        want to re-use them (much recommended!).

-       

-        Sort Files within Lists

-       

-        A strange behavior of Windows is to not respect the order of the 
-        files dropped in a window. To help cure this silly habit, you can 
-        sort all the file names of all the groups already entered.

-       

-        Note however that Drag & Dropped files are automatically sorted.

-       

-        This is an important issue, as we're going to process files in 
-        parallel between groups!

-       

-        Number of Groups:

-       

-        Just a counter of the number of groups entered.

-       

-        Summary list of all groups

-       

-        One group is displayed per line.

-       

-        Expression

-       

-        Enter the expression to be 
-        evaluated. Be sure you have entered all the groups needed by your expression!

-       

-        Output File Type

-       

-         

-       

-        EP (text)

-       

-        Text file, see the .ep file specification.

-       

-        EPH (text)

-       

-        Text file, see the .eph file specification.

-       

-        SEF (binary)

-       

-        Binary file, see the .sef file specification.

-       

-        Compact format which can handle all the basic informations for EEG.

-       

-        EDF (binary)

-       

-        Binary file, see the .edf file specification.

-       

-        Useful only for data interchange, otherwise don't use (loss of precision)!

-       

-        RIS (binary)

-       

-        Binary file, see the .ris file specification.

-       

-        Produced by the matrix multiplication / Inverse Solution computation.

-       

-        Options

-       

-         

-       

-        Output Directory

-       

-        What it says: where to put the results!

-       

-        Generate file names as:

-       

-         

-       

-        Compound of Operations

-       

-        Each file name will hold a condensed version of the operations 
-        applied from the originals. See this note.

-       

-        Use this if you want to remember precisely what are your files, f.ex. 
-        for Inverse Solutions. Be aware that too many operations will 
-        generate very long and unreadible file names, and can even crash Cartool.

-       

-        Simply Numbered

-       

-        Just generate file names as a numbered list. See this note.

-       

-        Process

-       

-        Run the batch processing.

-       

-        The button remains disabled until all parameters are OK.

-       

-        Cancel

-       

-        Quit the dialog.

-       

-        Help

-       

-        Launch the Help to the right page (should be here...).

-   

-  

-   Expressions

-  

-   You have to provide a mathematical expression to be applied on 
-   your files.

-  

-   First understand what is meant by groups of files, then see 
-   what operations can be applied to them.

-  

-   Groups of files

-  

-   Operands are usually whole sets of files, and each set should have 
-   some coherence of its own:

-  
    
-   
  • 
-   
    
-    Having some sort of semantic associated to it, f.ex. all the 
-    subjects for 1 condition, or all the epochs of 1 subject etc...
    
-   
  • 
-   
    
-    Having the same number of electrodes / solution points & same
-     number of time frames among files.
    
-   
  • 
-   
    
-    Preferably files being of the same types, i.e. not mixing 
-    scalar and vector values.
    
-   
  • 
-   
    
-    Preferaby files having the same extensions, but not mandatory.
    
-   

-  

-    

-  

-   Among groups, however, sizes and types can differ. However a 
-   given operation should receive compatible groups, f.ex.:

-  
    
-   
  • 
-   
    
-    Summing, subtracting etc... between 2 groups: both groups should have 
-    the same number of electrodes, time frames, and number of files.
    
-   
  • 
-   
    
-    Multiplying matrices with EEG: the usual Line / Column dimensions 
-    criterion should be satisfied.
    
-   

-  

-    

-  

-   Groups are used by sequentially and synchronically processing each 
-   of their files, f.ex. summing all the files of two groups:

-  

-   

-    
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-    

-       

-        Group1

-       

-        Group2

-       

-        "+" operation

-       

-        cond1.subj1

-       

-        cond2.subj1

-       

-        cond1.subj1 + cond2.subj1

-       

-        cond1.subj2

-       

-        cond2.subj2

-       

-        cond1.subj2 + cond2.subj2

-       

-        cond1.subj3

-       

-        cond2.subj3

-       

-        cond1.subj3 + cond2.subj3

-       

-        ...

-       

-        ...

-       

-        ...

-       

-        cond1.subjn

-       

-        cond2.subjn

-       

-        cond1.subjn + cond2.subjn

-   

-  

-    

-  

-   Matrix multiplication, though, is a special case. One matrix 
-   is taken, then all the EEG are multiplied to it, then the next 
-   matrix, and so on:

-  

-   

-    
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-    

-       

-        Group1

-       

-        Group2

-       

-        "*" operation

-       

-        matrix1

-       

-        subj1

-        subj2

-        subj3

-        ...

-        subjn

-       

-        matrix1 * subj1

-        matrix1 * subj2

-        matrix1 * subj3

-        ...

-        matrix1 * subjn

-       

-        matrix2

-       

-        subj1

-        subj2

-        subj3

-        ...

-        subjn

-       

-        matrix2 * subj1

-        matrix2 * subj2

-        matrix2 * subj3

-        ...

-        matrix2 * subjn

-       

-        ...

-       

-        ...

-       

-        ...

-       

-        matrixm

-       

-        subj1

-        subj2

-        subj3

-        ...

-        subjn

-       

-        matrixm * subj1

-        matrixm * subj2

-        matrixm * subj3

-        ...

-        matrixm * subjn

-   

-  

-   Operations & functions available

-  

-   Group, Group1, Group2... are groups of files.

-   Value is a scalar value.

-   Vector3D is a 3D vector (x, y, z).

-  

-    

-  

-   

-    
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-    

-       

-        Operation & operands

-       

-        Description

-       

-        Type of results

-       

-        Group + Value

-        Value + Group

-       

-        Add a constant value to a group of files.

-        Input files should contain scalar values.

-       

-        Group,

-        scalar values

-       

-        Group + Vector3D

-       

-        Add a constant vector to a group of files.

-        Input files should contain 3D vectors.

-       

-        Group,

-        3D vectors

-       

-        Group1 + Group2

-       

-        Sum all files of Group1 with the files of Group2.

-        Input files should both contain either scalar values or 3D vectors, 
-        but not a mix of the two.

-       

-        Group,

-        scalar values if input are scalar values,

-        3D vectors if input are 3D vectors

-       

-        Group - Value

-       

-        Subtract a constant value to a group of files.

-        Input files should contain scalar values.

-       

-        Group,

-        scalar values

-       

-        Group - Vector3D

-       

-        Subtract a constant vector to a group of files.

-        Input files should contain 3D vectors.

-       

-        Group,

-        3D vectors

-       

-        Group1 - Group2

-       

-        Subtract all files of Group1 with the files of Group2.

-        Input files should both contain either scalar values or 3D vectors, 
-        but not a mix of the two.

-       

-        Group,

-        scalar values if input are scalar values,

-        3D vectors if input are 3D vectors

-       

-        Group * Value

-        Value * Group

-       

-        Multiply the group of files by a constant value.

-        Input files could contain either scalar values or 3D vectors.

-       

-        Group,

-        scalar values if input are scalar values,

-        3D vectors if input are 3D vectors

-       

-        Group1 * Group2

-       

-        Multiply all files from Group1 by the files of Group2.

-        Group1 should contain matrices.

-        Group2 should contain files of 2D data, like EEG.

-       

-        Group,

-        scalar values or 3D vectors according to each matrix

-       

-        Group / Value

-       

-        Divide the group of files by a constant value.

-        Input files could contain either scalar values or 3D vectors.

-       

-        Group,

-        scalar values if input are scalar values,

-        3D vectors if input are 3D vectors

-   

-  

-   

-     

-   

-  

-   

-    
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-    

-       

-        Function & operands

-       

-        Description

-       

-        Type of results

-       

-        Abs ( Group )

-       

-        Input files are scalar values: absolute values.

-        Input files are 3D vectors: norm of the vectors.

-       

-        Group,

-        scalar values

-       

-        Scalar ( Group )

-       

-        Input files are scalar values: values untouched.

-        Input files are 3D vectors: norm of the vectors.

-       

-        Group,

-        scalar values

-       

-        Sqr ( Group )

-       

-        Input files are scalar values: the square of the values.

-        Input files are 3D vectors: square of the norm of the vectors.

-       

-        Group,

-        scalar values

-       

-        Sqrt ( Group )

-       

-        Input files are scalar values: the square root of the values.

-        Input files are 3D vectors: not allowed.

-       

-        Group,

-        scalar values

-   

-  

-    

-  

-   Examples of expressions

-  

-   

-    
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-    

-       

-        Group1

-       

-        Handy to just rename a bunch of files, and / or convert format. Check Simply
-         Numbered from the Generate file names option.

-       

-        Group1 * Group2

-       

-        Compute the results of Inverse Solutions, if Group1 holds the 
-        matrices and Group2 the EEG.

-        Outputted .ris 
-        files can be either scalar or vectorial.

-       

-        See the next paragraph for more on IS.

-       

-        Group1 - Group2

-       

-        Compute the differences between two sets of files.

-        This could be either 2 EEGs or 2 results from Inverse Solution. In 
-        the last case, they can correctly be either of scalar or vectorial types.

-       

-        ( 3 * Group1 + 2 * Group2 ) / 5

-       

-        Do a weighted sum of two groups.

-        Groups can be either scalars or vectorials.

-   

-  

-   Computing "Results of Inverse Solutions"

-  

-   !New!

-  

-   It is now strongly recommended to use the new 
-   dedicated tool to compute the results 
-   of inverse solutions.

-  

-   This tool offers much more controls over this process, like preprocessing 
-   filter, postprocessing standardization, per group average etc... It also 
-   performs numerous consistency checks on all the input files, so the results 
-   are also safer.

-  

-   Use that tool - now.

-  

-   The old way - if you really insist:

-  

-   You can use the File Calculator to 
-   produce the final stage of the Inverse Solution, what we call Results 
-   of Inverse Solution, or RIS (see .ris 
-   files). Provided one or more matrix(ces)
-    of Inverse Solution, you can batch this computation according to 
-   your needs.

-  

-   To see how you can compute the inverse matrices, go here,
-    and to see how you can use these matrices for display, go here.

-  

-    

-  

-   Say we dropped the matrices into Group1, and some ERPs for two 
-   conditions into Group2 and Group3 respectively. Here 
-   are the most common options to compute the results of inverse 
-   solutions (which one is "the right one" depends on your 
-   experiment, paradigm and tests):

-  

-    

-  

-   

-    
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-     
-      
-      
-     
-    

-       

-        Group1 * Group2

-       

-        and

-       

-        Group1 * Group3

-       

-        Multiplying the matrices by the EEGs 
-        is the basic operation.

-       

-        The resulting files can either hold vectors (the most common 
-        cases) or scalar values for each solution points location, 
-        which is quite important to know for your next steps (usually, statistics).

-       

-        Scalar ( Group1 * Group2 )

-       

-        and

-       

-        Scalar ( Group1 * Group3 )

-       

-        We can add a step to the multiplication, by 
-        forcing the results to be scalar values.

-       

-        If the results of the multiplication are vectors, the Scalar 
-        operation will convert them to their (Euclidian) norm. This is 
-        the same as the Abs function.

-       

-        If the results of the multiplication are already scalars, the Scalar 
-        operation will do nothing. This is not the same as the Abs 
-        function, as the Abs will remove the sign of the scalar 
-        values, which Scalar does preserve.

-       

-        Group1 * ( Group2 - Group3 )

-       

-        or

-       

-        Group1 * Group2 - Group1 * Group3

-       

-        We can compute the difference in the inverse solution space between 
-        the two conditions. The two formula are mathematically equivalent, 
-        though the former is faster (2 operations, and only one multiplication).

-       

-        This formula accounts for the directions of the vectors in the 
-        inverse space: vectors are being subtracted between the 2 conditions.

-       

-        Abs ( Group1 * ( Group2 - Group3 ) )

-       

-        or

-       

-        Abs ( Group1 * Group2 - Group1 * Group3 )

-       

-        Same as above, then converting to the absolute / norm values. We end 
-        up with the intensity of the vectorial differences between the 
-        two conditions.

-       

-        Scalar ( Group1 * Group2 )

-        - Scalar ( Group1 * Group3 )

-       

-        For vectorial inverse, this computes the difference of intensities 
-        between the two conditions, without accounting whatsoever with the 
-        directions of the vectors.

-       

-        For scalar inverse, this computes the difference of (signed) values 
-        between the two conditions

-       

-        Results are signed scalar values (positive and negative).

-       

-        Abs ( Scalar ( Group1 * Group2 )

-        - Scalar ( Group1 * Group3 ) )

-       

-         

-       

-        Same as above, then converting all differences into positive values.

-       

-        Abs ( Abs ( Group1 * Group2 )

-        - Abs ( Group1 * Group3 ) )

-       

-        We compute here the difference of absolute intensities between 
-        the two conditions (without, for the vectorial inverse, accounting 
-        whatsoever for the directions of the vectors).

-       

-        Results are positive scalar values.

-       

-        Abs ( Sqr ( Group1 * Group2 )

-        - Sqr ( Group1 * Group3 ) )

-       

-        Just a variation of the previous formula, giving the absolute 
-        difference of powers between the two conditions.

-   

-  

-   File Calculator - Results

-  
    
-   
  • 
-   
    
-    Processed files are written in the base directory. File names 
-    can be either a compound of the applied operations, or a simple 
-    numbered list of files based on the base directory name. Extension is 
-    the one specified in the paramaters.
    
-   
  • 
-   
    
-    The type of results will depend on what you asked for, f.ex. 
-    it is usually scalar values ("numbers"), but it can 
-    be vectors, as from the Inverse Solution computation.
    
-   
  • 
-   
    
-    The dimensions of the results also depends on the operations 
-    applied, so they can have different sizes as compared to the input files.
    
-   
  • 
-   
    
-    Verbose file .vrb 
-    (text), showing all the parameters.
    
-   

-  

-   File Calculator - Technical points and hints

-  

-   Output file names

-  

-   By default, Cartool will generate file names 
-   that reflect the whole set of operations. These are not exact 
-   replicas of the expression, but rather a construction derived of it. 
-   This is meant to help remember what operations have been done on the files.

-  

-   To do so, it will use the original file names, insert the operators / 
-   functions used one at a time, then optinally shrink the resulting 
-   file names if they appear to be too long. F.ex.:

-  
    
-   
  • 
-   
    
-    Expression  Group1 - Group2  can generate  basprr4-basviri4.eph
    
-   
  • 
-   
    
-    Expression  Scalar ( Group1 * ( Group2 - Group3 ) )  
-    can generate  Scalar(Avg152tSmacProSph.lorb1.basprr4-basviri4).ris
    
-   

-  

-    

-  

-   One problem arises with operator like * / and the like, which Windows 
-   does not want at all in file names. In these cases, a 
-   "." (dot) is used instead of the operator.

-  

-    

-  

-   If not a compound of operations, file names will simply repeat the 
-   last directory part of the Base Directory, then add an index value, f.ex.:

-  
    
-   
    
-    Calc G1-G2.0001.eph
    
-    Calc G1-G2.0002.eph
    
-    Calc G1-G2.0003.eph
    
-    etc...
    
-   

-  

-   Disk space

-  

-   All these operations will use the disk to store the temporary and the 
-   final results. There is no way to do otherwise, as you know, this is 
-   a batch tool! Plus you can process gigabytes of data.

-  

-   Consequently, think of having some significant room left on your 
-   hard drive! The more elaborated your expression, the more space 
-   you need, but as a rule of thumb, say you need 3 times the amount of 
-   data you process in free space (if data are already in binary format, 
-   otherwise, maybe 2 times should be fine).

-  

-   Errors

-  

-   Some errors in your expression can be detected when you start the 
-   processing, like missing parenthesis, missing operands and the like.

-  

-   But some other errors will be only be found when reaching the 
-   problematic part, like wrong types of operands (adding vectors to scalars).

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    
+ 
+     

+         

+             File Calculator
+         

+         

+              
+         

+         

+             What is the File Calculator?
How to run the File Calculator

+             Expressions
+         

+         
+         

+             Results of Inverse Solution

+             Results
Technical points and hints
+         

+         

+             What is the File Calculator?
+         

+         

+             This is a tool to batch-process sets of files with a 
+                 mathematical
+                 expression
+              of your liking. There can be many sets of files to
+             use, but each set should be somehow a coherent one, f.ex. all the
+             files of all subjects for one condition. Expressions are composed
+             with elementary operations, see below.
+         

+         

+             How to run the File Calculator
+         

+         

+             Call the dialog from 
+                 
+                     Tools
+                     | File Calculator
+                 
+              menu.
+         

+         

+             The following dialog pops out. Fill the parameters which are relevant
+             for you, drop the sets of files to process, then click either
+             on the Process button:
+         

+         

+             

+                 
+             

+         

+         

+             

+                 
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                 

+                             

+                                 Groups of Files
+                         

+                             

+                                 You can Drag & Drop files here.
+                         

+                             

+                                 Add New Group of Files
+                         

+                             

+                                 Enter a new group of files.
+                             

+                             

+                                 See this note about groups.
+                         

+                             

+                                 Remove Last Group
+                         

+                             

+                                 Does what it says (amazing).
+                         

+                             

+                                 Clear All Groups
+                         

+                             

+                                 Clear out all the groups at once.
+                         

+                             

+                                 Read Lists from File
+                         

+                             

+                                 You can direclty retrieve the lists of groups previously saved.
+                         

+                             

+                                 Write Lists to File
+                         

+                             

+                                 You can save the lists of current groups into a file, in case you
+                                 want to re-use them (much recommended!).
+                         

+                             

+                                 Sort Files within Lists
+                         

+                             

+                                 A strange behavior of Windows is to not respect the order of the
+                                 files dropped in a window. To help cure this silly habit, you can
+                                 sort all the file names of all the groups already entered.
+                             

+                             

+                                 Note however that Drag & Dropped files are automatically sorted.
+                             

+                             

+                                 This is an important issue, as we're going to process files in
+                                 parallel between groups!
+                         

+                             

+                                 Number of Groups:
+                         

+                             

+                                 Just a counter of the number of groups entered.
+                         

+                             

+                                 Summary list of all groups
+                         

+                             

+                                 One group is displayed per line.
+                         

+                             

+                                 Expression
+                         

+                             

+                                 Enter the expression to be
+                                 evaluated. Be sure you have entered all the groups needed by your expression!
+                         

+                             

+                                 Output File Type
+                         

+                             

+                                  
+                         

+                             

+                                 EP (text)
+                         

+                             

+                                 Text file, see the .ep file specification.
+                         

+                             

+                                 EPH (text)
+                         

+                             

+                                 Text file, see the .eph file specification.
+                         

+                             

+                                 SEF (binary)
+                         

+                             

+                                 Binary file, see the .sef file specification.
+                             

+                             

+                                 Compact format which can handle all the basic informations for EEG.
+                         

+                             

+                                 EDF (binary)
+                         

+                             

+                                 Binary file, see the .edf file specification.
+                             

+                             

+                                 Useful only for data interchange, otherwise don't use (loss of precision)!
+                         

+                             

+                                 RIS (binary)
+                         

+                             

+                                 Binary file, see the .ris file specification.
+                             

+                             

+                                 Produced by the matrix multiplication / Inverse Solution computation.
+                         

+                             

+                                 Options
+                         

+                             

+                                  
+                         

+                             

+                                 Output Directory
+                         

+                             

+                                 What it says: where to put the results!
+                         

+                             

+                                 Generate file names as:
+                         

+                             

+                                  
+                         

+                             

+                                 Compound of Operations
+                         

+                             

+                                 Each file name will hold a condensed version of the operations
+                                 applied from the originals. See this note.
+                             

+                             

+                                 Use this if you want to remember precisely what are your files, f.ex.
+                                 for Inverse Solutions. Be aware that too many operations will
+                                 generate very long and unreadible file names, and can even crash Cartool.
+                         

+                             

+                                 Simply Numbered
+                         

+                             

+                                 Just generate file names as a numbered list. See this note.
+                         

+                             

+                                 Process
+                         

+                             

+                                 Run the batch processing.
+                             

+                             

+                                 The button remains disabled until all parameters are OK.
+                         

+                             

+                                 Cancel
+                         

+                             

+                                 Quit the dialog.
+                         

+                             

+                                 Help
+                         

+                             

+                                 Launch the Help to the right page (should be here...).
+                         

+             

+         

+         

+             Expressions
+         

+         

+             You have to provide a mathematical expression to be applied on
+             your files.
+         

+         

+             First understand what is meant by groups of files, then see
+             what operations can be applied to them.
+         

+         

+             Groups of files
+         

+         

+             Operands are usually whole sets of files, and 
+                 each set should have
+                 some coherence of its own
+             :
+         

+         
    
+             
  • 
+                 
    
+                     Having some sort of semantic associated to it, f.ex. all the
+                     subjects for 1 condition, or all the epochs of 1 subject etc...
+                 
    
+             
  • 
+                 
    
+                     Having the same number of electrodes / solution points & 
+                         same
+                         number of time frames
+                      among files.
+                 
    
+             
  • 
+                 
    
+                     Preferably files being of the same types, i.e. not mixing
+                     scalar and vector values.
+                 
    
+             
  • 
+                 
    
+                     Preferaby files having the same extensions, but not mandatory.
+                 
    
+         

+         

+              
+         

+         

+             Among groups, however, sizes and types can differ. However a
+             given operation should receive compatible groups, f.ex.:
+         

+         
    
+             
  • 
+                 
    
+                     Summing, subtracting etc... between 2 groups: both groups should have
+                     the same number of electrodes, time frames, and number of files.
+                 
    
+             
  • 
+                 
    
+                     Multiplying matrices with EEG: the usual Line / Column dimensions
+                     criterion should be satisfied.
+                 
    
+         

+         

+              
+         

+         

+             Groups are used by 
+                 sequentially and synchronically processing each
+                 of their files
+             , f.ex. summing all the files of two groups:
+         

+         

+             

+                 
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                 

+                             

+                                 Group1
+                         

+                             

+                                 Group2
+                         

+                             

+                                 "+" operation
+                         

+                             

+                                 cond1.subj1
+                         

+                             

+                                 cond2.subj1
+                         

+                             

+                                 cond1.subj1 + cond2.subj1
+                         

+                             

+                                 cond1.subj2
+                         

+                             

+                                 cond2.subj2
+                         

+                             

+                                 cond1.subj2 + cond2.subj2
+                         

+                             

+                                 cond1.subj3
+                         

+                             

+                                 cond2.subj3
+                         

+                             

+                                 cond1.subj3 + cond2.subj3
+                         

+                             

+                                 ...
+                         

+                             

+                                 ...
+                         

+                             

+                                 ...
+                         

+                             

+                                 cond1.subjn
+                         

+                             

+                                 cond2.subjn
+                         

+                             

+                                 cond1.subjn + cond2.subjn
+                         

+             

+         

+         

+              
+         

+         

+             Matrix multiplication, though, is a special case. One matrix
+             is taken, then all the EEG are multiplied to it, then the next
+             matrix, and so on:
+         

+         

+             

+                 
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                 

+                             

+                                 Group1
+                         

+                             

+                                 Group2
+                         

+                             

+                                 "*" operation
+                         

+                             

+                                 matrix1
+                         

+                             

+                                 subj1

+                                 subj2

+                                 subj3

+                                 ...

+                                 subjn
+                         

+                             

+                                 matrix1 * subj1

+                                 matrix1 * subj2

+                                 matrix1 * subj3

+                                 ...

+                                 matrix1 * subjn
+                         

+                             

+                                 matrix2
+                         

+                             

+                                 subj1

+                                 subj2

+                                 subj3

+                                 ...

+                                 subjn
+                         

+                             

+                                 matrix2 * subj1

+                                 matrix2 * subj2

+                                 matrix2 * subj3

+                                 ...

+                                 matrix2 * subjn
+                         

+                             

+                                 ...
+                         

+                             

+                                 ...
+                         

+                             

+                                 ...
+                         

+                             

+                                 matrixm
+                         

+                             

+                                 subj1

+                                 subj2

+                                 subj3

+                                 ...

+                                 subjn
+                         

+                             

+                                 matrixm * subj1

+                                 matrixm * subj2

+                                 matrixm * subj3

+                                 ...

+                                 matrixm * subjn
+                         

+             

+         

+         

+             Operations & functions available
+         

+         

+             Group, Group1, Group2... are groups of files.

+             Value is a scalar value.

+             Vector3D is a 3D vector (x, y, z).
+         

+         

+              
+         

+         

+             

+                 
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                 

+                             

+                                 Operation & operands
+                         

+                             

+                                 Description
+                         

+                             

+                                 Type of results
+                         

+                             

+                                 Group + Value

+                                 Value + Group
+                         

+                             

+                                 Add a constant value to a group of files.

+                                 Input files should contain scalar values.
+                         

+                             

+                                 Group,

+                                 scalar values
+                         

+                             

+                                 Group + Vector3D
+                         

+                             

+                                 Add a constant vector to a group of files.

+                                 Input files should contain 3D vectors.
+                         

+                             

+                                 Group,

+                                 3D vectors
+                         

+                             

+                                 Group1 + Group2
+                         

+                             

+                                 Sum all files of Group1 with the files of Group2.

+                                 Input files should both contain either scalar values or 3D vectors,
+                                 but not a mix of the two.
+                         

+                             

+                                 Group,

+                                 scalar values if input are scalar values,

+                                 3D vectors if input are 3D vectors
+                         

+                             

+                                 Group - Value
+                         

+                             

+                                 Subtract a constant value to a group of files.

+                                 Input files should contain scalar values.
+                         

+                             

+                                 Group,

+                                 scalar values
+                         

+                             

+                                 Group - Vector3D
+                         

+                             

+                                 Subtract a constant vector to a group of files.

+                                 Input files should contain 3D vectors.
+                         

+                             

+                                 Group,

+                                 3D vectors
+                         

+                             

+                                 Group1 - Group2
+                         

+                             

+                                 Subtract all files of Group1 with the files of Group2.

+                                 Input files should both contain either scalar values or 3D vectors,
+                                 but not a mix of the two.
+                         

+                             

+                                 Group,

+                                 scalar values if input are scalar values,

+                                 3D vectors if input are 3D vectors
+                         

+                             

+                                 Group * Value

+                                 Value * Group
+                         

+                             

+                                 Multiply the group of files by a constant value.

+                                 Input files could contain either scalar values or 3D vectors.
+                         

+                             

+                                 Group,

+                                 scalar values if input are scalar values,

+                                 3D vectors if input are 3D vectors
+                         

+                             

+                                 Group1 * Group2
+                         

+                             

+                                 Multiply all files from Group1 by the files of Group2.

+                                 Group1 should contain matrices.

+                                 Group2 should contain files of 2D data, like EEG.
+                         

+                             

+                                 Group,

+                                 scalar values or 3D vectors according to each matrix
+                         

+                             

+                                 Group / Value
+                         

+                             

+                                 Divide the group of files by a constant value.

+                                 Input files could contain either scalar values or 3D vectors.
+                         

+                             

+                                 Group,

+                                 scalar values if input are scalar values,

+                                 3D vectors if input are 3D vectors
+                         

+             

+         

+         

+             

+                  
+             

+         

+         

+             

+                 
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                 

+                             

+                                 Function & operands
+                         

+                             

+                                 Description
+                         

+                             

+                                 Type of results
+                         

+                             

+                                 Abs ( Group )
+                         

+                             

+                                 Input files are scalar values: absolute values.

+                                 Input files are 3D vectors: norm of the vectors.
+                         

+                             

+                                 Group,

+                                 scalar values
+                         

+                             

+                                 Scalar ( Group )
+                         

+                             

+                                 Input files are scalar values: values untouched.

+                                 Input files are 3D vectors: norm of the vectors.
+                         

+                             

+                                 Group,

+                                 scalar values
+                         

+                             

+                                 Sqr ( Group )
+                         

+                             

+                                 Input files are scalar values: the square of the values.

+                                 Input files are 3D vectors: square of the norm of the vectors.
+                         

+                             

+                                 Group,

+                                 scalar values
+                         

+                             

+                                 Sqrt ( Group )
+                         

+                             

+                                 Input files are scalar values: the square root of the values.

+                                 Input files are 3D vectors: not allowed.
+                         

+                             

+                                 Group,

+                                 scalar values
+                         

+             

+         

+         

+              
+         

+         

+             Examples of expressions
+         

+         

+             

+                 
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                 

+                             

+                                 Group1
+                         

+                             

+                                 Handy to just rename a bunch of files, and / or convert format. Check 
+                                     Simply
+                                     Numbered
+                                  from the Generate file names option.
+                         

+                             

+                                 Group1 * Group2
+                         

+                             

+                                 Compute the results of Inverse Solutions, if Group1 holds the
+                                 matrices and Group2 the EEG.

+                                 Outputted .ris
+                                 files can be either scalar or vectorial.
+                             

+                             

+                                 See the next paragraph for more on IS.
+                         

+                             

+                                 Group1 - Group2
+                         

+                             

+                                 Compute the differences between two sets of files.

+                                 This could be either 2 EEGs or 2 results from Inverse Solution. In
+                                 the last case, they can correctly be either of scalar or vectorial types.
+                         

+                             

+                                 ( 3 * Group1 + 2 * Group2 ) / 5
+                         

+                             

+                                 Do a weighted sum of two groups.

+                                 Groups can be either scalars or vectorials.
+                         

+             

+         

+         

+             Computing "Results of Inverse Solutions"
+         

+         

+             !New!
+         

+         

+             It is now strongly recommended to use the new
+             dedicated tool to 
+                 
+                     compute the results
+                     of inverse solutions
+                 
+             .
+         

+         

+             This tool offers much more controls over this process, like preprocessing
+             filter, postprocessing standardization, per group average etc... It also
+             performs numerous consistency checks on all the input files, so the results
+             are also safer.
+         

+         

+             Use that tool - now.
+         

+         

+             The old way - if you really insist:
+         

+         

+             You can use the File Calculator to
+             produce the final stage of the Inverse Solution, what we call Results
+             of Inverse Solution, or RIS (see .ris
+             files). Provided one or more 
+                 matrix(ces)
+                 of Inverse Solution
+             , you can batch this computation according to
+             your needs.
+         

+         

+             To see how you can compute the inverse matrices, go here,
+             and to see how you can use these matrices for display, go here.
+         

+         

+              
+         

+         

+             Say we dropped the matrices into Group1, and some ERPs for two
+             conditions into Group2 and Group3 respectively. Here
+             are the most common options to compute the results of inverse
+             solutions (which one is "the right one" depends on your
+             experiment, paradigm and tests):
+         

+         

+              
+         

+         

+             

+                 
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                     
+                         
+                         
+                     
+                 

+                             

+                                 Group1 * Group2
+                             

+                             

+                                 and
+                             

+                             

+                                 Group1 * Group3
+                         

+                             

+                                 
+                                     Multiplying the matrices by the EEGs
+                                     is the basic operation.
+                                 
+                             

+                             

+                                 The resulting files can either hold vectors (the most common
+                                 cases) or scalar values for each solution points location,
+                                 which is quite important to know for your next steps (usually, statistics).
+                         

+                             

+                                 Scalar ( Group1 * Group2 )
+                             

+                             

+                                 and
+                             

+                             

+                                 Scalar ( Group1 * Group3 )
+                         

+                             

+                                 We can add a step to the multiplication, by
+                                 forcing the results to be scalar values.
+                             

+                             

+                                 If the results of the multiplication are vectors, the Scalar
+                                 operation will convert them to their (Euclidian) norm. This is
+                                 the same as the Abs function.
+                             

+                             

+                                 If the results of the multiplication are already scalars, the Scalar
+                                 operation will do nothing. This is not the same as the Abs
+                                 function, as the Abs will remove the sign of the scalar
+                                 values, which Scalar does preserve.
+                         

+                             

+                                 Group1 * ( Group2 - Group3 )
+                             

+                             

+                                 or
+                             

+                             

+                                 Group1 * Group2 - Group1 * Group3
+                         

+                             

+                                 We can compute the difference in the inverse solution space between
+                                 the two conditions. The two formula are mathematically equivalent,
+                                 though the former is faster (2 operations, and only one multiplication).
+                             

+                             

+                                 This formula accounts for the directions of the vectors in the
+                                 inverse space: vectors are being subtracted between the 2 conditions.
+                         

+                             

+                                 Abs ( Group1 * ( Group2 - Group3 ) )
+                             

+                             

+                                 or
+                             

+                             

+                                 Abs ( Group1 * Group2 - Group1 * Group3 )
+                         

+                             

+                                 Same as above, then converting to the absolute / norm values. We end
+                                 up with the intensity of the vectorial differences between the
+                                 two conditions.
+                         

+                             

+                                 Scalar ( Group1 * Group2 )

+                                 - Scalar ( Group1 * Group3 )
+                         

+                             

+                                 For vectorial inverse, this computes the difference of intensities
+                                 between the two conditions, without accounting whatsoever with the
+                                 directions of the vectors.
+                             

+                             

+                                 For scalar inverse, this computes the difference of (signed) values
+                                 between the two conditions
+                             

+                             

+                                 Results are signed scalar values (positive and negative).
+                         

+                             

+                                 Abs ( Scalar ( Group1 * Group2 )

+                                 - Scalar ( Group1 * Group3 ) )
+                             

+                             

+                                  
+                         

+                             

+                                 Same as above, then converting all differences into positive values.
+                         

+                             

+                                 Abs ( Abs ( Group1 * Group2 )

+                                 - Abs ( Group1 * Group3 ) )
+                         

+                             

+                                 We compute here the difference of absolute intensities between
+                                 the two conditions (without, for the vectorial inverse, accounting
+                                 whatsoever for the directions of the vectors).
+                             

+                             

+                                 Results are positive scalar values.
+                         

+                             

+                                 Abs ( Sqr ( Group1 * Group2 )

+                                 - Sqr ( Group1 * Group3 ) )
+                         

+                             

+                                 Just a variation of the previous formula, giving the absolute
+                                 difference of powers between the two conditions.
+                         

+             

+         

+         

+             File Calculator - Results
+         

+         
    
+             
  • 
+                 
    
+                     Processed files are written in the base directory. File names
+                     can be either a compound of the applied operations, or a simple
+                     numbered list of files based on the base directory name. Extension is
+                     the one specified in the paramaters.
+                 
    
+             
  • 
+                 
    
+                     The type of results will depend on what you asked for, f.ex.
+                     it is usually scalar values ("numbers"), but it can
+                     be vectors, as from the Inverse Solution computation.
+                 
    
+             
  • 
+                 
    
+                     The dimensions of the results also depends on the operations
+                     applied, so they can have different sizes as compared to the input files.
+                 
    
+             
  • 
+                 
    
+                     Verbose file .vrb
+                     (text), showing all the parameters.
+                 
    
+         

+         

+             File Calculator - Technical points and hints
+         

+         

+             Output file names
+         

+         

+             By default, Cartool will generate file names
+             that reflect the whole set of operations. These are not exact
+             replicas of the expression, but rather a construction derived of it.
+             This is meant to help remember what operations have been done on the files.
+         

+         

+             To do so, it will use the original file names, insert the operators /
+             functions used one at a time, then optinally shrink the resulting
+             file names if they appear to be too long. F.ex.:
+         

+         
    
+             
  • 
+                 
    
+                     Expression  Group1 - Group2  can generate  basprr4-basviri4.eph
+                 
    
+             
  • 
+                 
    
+                     Expression  Scalar ( Group1 * ( Group2 - Group3 ) ) 
+                     can generate  Scalar(Avg152tSmacProSph.lorb1.basprr4-basviri4).ris
+                 
    
+         

+         

+              
+         

+         

+             One problem arises with operator like * / and the like, which Windows
+             does not want at all in file names. In these cases, a
+             "." (dot) is used instead of the operator.
+         

+         

+              
+         

+         

+             If not a compound of operations, file names will simply repeat the
+             last directory part of the Base Directory, then add an index value, f.ex.:
+         

+         
    
+             
    
+                 Calc G1-G2.0001.eph
    
+                 Calc G1-G2.0002.eph
    
+                 Calc G1-G2.0003.eph
    
+                 etc...
+             
    
+         

+         

+             Disk space
+         

+         

+             All these operations will use the disk to store the temporary and the
+             final results. There is no way to do otherwise, as you know, this is
+             a batch tool! Plus you can process gigabytes of data.
+         

+         

+             Consequently, 
+                 think of having some significant room left on your
+                 hard drive
+             ! The more elaborated your expression, the more space
+             you need, but as a rule of thumb, say you need 3 times the amount of
+             data you process in free space (if data are already in binary format,
+             otherwise, maybe 2 times should be fine).
+         

+         

+             Errors
+         

+         

+             Some errors in your expression can be detected when you start the
+             processing, like missing parenthesis, missing operands and the like.
+         

+         

+             But some other errors will be only be found when reaching the
+             problematic part, like wrong types of operands (adding vectors to scalars).
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+     

  
 
\ No newline at end of file
diff --git a/docs/ReferenceGuide/files-formats-cartool.html b/docs/ReferenceGuide/files-formats-cartool.html
index 20ae996c..2e43cecb 100644
--- a/docs/ReferenceGuide/files-formats-cartool.html
+++ b/docs/ReferenceGuide/files-formats-cartool.html
@@ -30,788 +30,1097 @@
 }
 
  
- 
-  

-   Appendix C

-   Cartool File Formats

-  

-    

-  

-   

-  

-   
-       
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-   

-      

-       .csv

-      

-       Comma Separated Values

-      

-       .data

-      

-       Data array

-      

-       .els

-      

-       ELectrodes Setup (complex cases)

-      

-       .ep

-      

-       Evoked Potentials

-      

-       .eph

-      

-       Evoked Potentials with Header

-      

-       .epsd

-      

-       .epse

-      

-       Evoked Potentials Standard Deviation / Standard Error

-      

-       .freq

-      

-       Frequencies

-      

-       .is

-      

-       Inverse Solution matrix

-      

-       .lf

-      

-       Lead Field file

-      

-       .lm

-      

-       Link Many file

-      

-       .mrk

-      

-       Marker file

-      

-       .mtg

-      

-       Montage file

-      

-       .ris

-      

-       Results of Inverse Solution computation

-      

-       .rois

-      

-       Regions Of Interest

-      

-       .sef

-      

-       Simple Eeg Format

-      

-       .seg

-      

-       Segmentation

-      

-       .spi

-      

-       Solution Points Irregularly spaced

-      

-       .spr

-      

-       Solution Points on Regular grid (obsolete)

-      

-       .tva

-      

-       Trigger VAlidation file

-      

-       .vrb

-      

-       Verbose file

-      

-       .xyz

-      

-       Electrodes coordinates (simpler case)

-  

-   .csv Comma Separated Values

-  

-   This is not a format defined by Cartool, but a very handy and well-recognized
-    file format to store an array of values (handled direclty 
-   by Excel, Statistica, Cartool...)

-  

-    

-  

-   Basically, it is a text file with values on each line being 
-   separated either by a comma (,) or by a semi-colon (;), 
-   according to your language settings (just to make simple things 
-   already complicated... but Cartool will gracefully read both). You 
-   can open them either with a text editor, or directly as a spreadsheet 
-   in Excel, Statistica, etc... (Note that Cartool also works with its 
-   equivalent Tab
-    Separated text file format)

-  

-    

-  

-   If you have problems and/or want to change the way Cartool, Excel or 
-   all other programs behave, do the following:

-  
    
-   
  • 
-   
    
-     go to the Control Panel, choose "Regional & Language Options"
    
-    
  • Click on "Customize"
    
-    
  • Change "List Separator" to force it to 
-    the character you prefer, but I recommend either a comma (,) 
-    or a semi-colon (;).
    
-   

-  

-    

-  

-   The content organization done by Cartool is the following:

-  
    
-   
  • 
-   
    
-    A first line which gives the names of the variables, 
-    and their sequence.
    
-    
  • Then each following lines contains the data 
-    themselves, with exactly the same number and same sequence of variables 
-    as the first line (padding with separators if needed).
    
-    
  • Two files with the same variable names but set in a different
-     order are equivalent., so you can import results / parameters 
-    from other programs quite easily.
    
-   

-  

-    

-  

-   Just an example to make it clear, a file used to hold the files 
-   parameters for the averaging process:
file;session;tva;triggers
E:\Data\Eeg1.eph;1;;1 2 3 4
E:\Data\Eeg1.eph;2;;5 6 7 8
E:\Data\Eeg2.eph;;;1 2 3 4 5 6 7 8

-   The first line enumerates the 4 variables (file, session etc...), and 
-   there are 3 lines of data with some of these variables defined, and 
-   some undefined.

-  

-   The order of the variables does not matter, and it could have be 
-   written as, f.ex.:
file;triggers;session;tva
E:\Data\Eeg1.eph;1 2 3 4;1;
E:\Data\Eeg1.eph;5 6 7 8;2;
E:\Data\Eeg2.eph;1 2 3 4 5 6 7 8;;

-   .data Data array

-  

-   A text file used to store and display any kind of 
-   informations, used for example in the segmentation
-    process.

-   It is a variant of the .seg format, please refer 
-   to it for the full explanations.

-  

-   The only difference is in the header (first two lines) which lacks 
-   the  number_of_clusters  variable:
number_of_files   number_of_time_frames
number_of_tracks   tracks_name1  tracks_name2  ...  tracks_namen

-   .els ELectrodes Setup

-  

-   A text file describing a setup of electrodes. It allows 
-   separate clusters of electrodes (for example 2 grids, or a few 
-   strips, or electrodes on the scalp plus some auxiliaries...), and 
-   each one of the clusters can be of a different type. Another (and 
-   obsolete) format is the .xyz.

-  

-   First line, a magic number:
ES01

-   Next 2 lines:
Total_number_of_electrodes
Number_of_clusters

-   Now repeat for each cluster (at least 1):
Cluster_name
Cluster_number_of_electrodes
Cluster_type

-   Cluster_type  could be seen as the dimensionality of the cluster:

-  
    
-   
  • 
-   
    
-    0 for separated electrodes (like auxiliaries), or "points"
    
-    
  • 1 for a strip of electrodes, or "line"
    
-    
  • 2 for a grid of electrodes, or "array"
    
-    
  • 3 for a 3D set of electrodes, usually 
-    on the scalp, that will be fitted by a 2D Delaunay triangulation 
-    surface (but in 3D...).
    
-   

-  

-   Then the list of coordinates, one per line:
x   y   z   label   optional_flag

-   x, y, z  are, of course, the coordinates, and label the name of 
-   the electrode. optional_flag can either be missing or be the 
-   identifier Bad, in which case it indicates that the electrodes 
-   has a non-significative signal (broken electrode, noisy signal, 
-   etc...), and though it will be geometrically used with its neighbors 
-   in the building of the 3D tesselation, the value of its signal will 
-   not appear to avoid spoiling the display.

-  

-    

-  

-   The idea of clustering electrodes is to isolate the interpolations 
-   between electrodes, so that different clusters won't interfere 
-   graphically. For example you can disjoin the auxiliaries electrodes, 
-   as you don't want to see them interpolated with regular Eeg.

-  

-   If two, or more, 3D clusters share the very same name, they will be 
-   merged into a single, big cluster of the same name. Still in the case 
-   some auxiliaries electrodes were recorded in the middle of regular 
-   electrodes, there are, say 3 clusters: 3D, auxs, 3D again, so the 
-   program understands that both 3D clusters are the same. If you don't 
-   want this merging, simply change the names!

-  

-    

-  

-   Example:
ES01
41
1
10-10 System
41
3
  1.000000E+0000  0.000000E+0000 -0.000000E+0000 Fpz
  8.090170E-0001  5.877853E-0001 -0.000000E+0000 AF7
  9.205049E-0001  0.000000E+0000  3.907311E-0001 AFz
  8.090170E-0001 -5.877853E-0001 -0.000000E+0000 AF8
  6.273924E-0001  7.217324E-0001  2.923717E-0001 F5
  6.590572E-0001  5.336940E-0001  5.299193E-0001 F3
  6.946584E-0001  0.000000E+0000  7.193398E-0001 Fz
  6.590572E-0001 -5.336940E-0001  5.299193E-0001 F4
  6.273924E-0001 -7.217324E-0001  2.923717E-0001 F6
  3.090170E-0001  9.510565E-0001 -0.000000E+0000 FT7
  3.367557E-0001  8.772786E-0001  3.420201E-0001 FC5
  3.535534E-0001  3.535534E-0001  8.660254E-0001 FC1
  3.583679E-0001  0.000000E+0000  9.335804E-0001 FCz
  3.535534E-0001 -3.535534E-0001  8.660254E-0001 FC2
  3.367557E-0001 -8.772786E-0001  3.420201E-0001 FC6
  3.090170E-0001 -9.510565E-0001 -0.000000E+0000 FT8
 -0.000000E+0000  1.000000E+0000 -0.000000E+0000 T3
 -0.000000E+0000  6.946584E-0001  7.193398E-0001 C3
 -0.000000E+0000  3.583679E-0001  9.335804E-0001 C1
  0               0               1              Cz
  3.885433E-0020 -3.583679E-0001  9.335804E-0001 C2
  7.531501E-0020 -6.946584E-0001  7.193398E-0001 C4
  1.084202E-0019 -1.000000E+0000 -0.000000E+0000 T4
 -3.090170E-0001  9.510565E-0001 -0.000000E+0000 TP7
 -3.367557E-0001  8.772786E-0001  3.420201E-0001 CP5
 -3.535534E-0001  3.535534E-0001  8.660254E-0001 CP1
 -3.583679E-0001 -0.000000E+0000  9.335804E-0001 CPz
 -3.535534E-0001 -3.535534E-0001  8.660254E-0001 CP2
 -3.367557E-0001 -8.772786E-0001  3.420201E-0001 CP6
 -3.090170E-0001 -9.510565E-0001 -0.000000E+0000 TP8
 -6.273924E-0001  7.217324E-0001  2.923717E-0001 P5
 -6.590572E-0001  5.336940E-0001  5.299193E-0001 P3
 -6.946584E-0001 -0.000000E+0000  7.193398E-0001 Pz
 -6.590572E-0001 -5.336940E-0001  5.299193E-0001 P4
 -6.273924E-0001 -7.217324E-0001  2.923717E-0001 P6
 -8.090170E-0001  5.877853E-0001 -0.000000E+0000 PO7
 -8.619499E-0001  4.019339E-0001  3.090170E-0001 PO3
 -9.205049E-0001 -0.000000E+0000  3.907311E-0001 POz
 -8.619499E-0001 -4.019339E-0001  3.090170E-0001 PO4
 -8.090170E-0001 -5.877853E-0001 -0.000000E+0000 PO8
 -1.000000E+0000 -0.000000E+0000 -0.000000E+0000 Oz

-   .ep Evoked Potentials

-  

-   A very basic text file format to store an ERP, without header. 
-   This is a simple matrix of values, each line (with end-of-line) 
-   having all the electrodes values for a given time frame:
electrode_1 electrode_2 electrode_3 ... electrode_n

-   Lines are repeated for each time frames (the number of time frames is 
-   therefore the number of lines). Cartool calculates the number of 
-   electrodes and the number of time frames by scanning the whole file 
-   at opening time. But it can not guess the sampling frequency, until 
-   the user specify it.

-  

-   .eph Evoked Potentials with Header

-  

-   A very basic text file format to store an ERP, with a small header.

-  

-   The first line is the header:
number_of_electrodes   number_of_time_frames   sampling_frequency

-   It is followed by the same block as in the .ep 
-   files. Cartool does not scan the whole file to get the number of 
-   electrodes etc... as they are read (and trusted) directly from the 
-   first line.

-  

-   .epsd  and  .epse 
-    Evoked Potentials Standard Deviation / Standard Error

-  

-   Actually, the format is just the same as the .eph one.

-  

-   It simply holds the Standard Deviation / Standard Error of an averaged file.

-  

-   .freq Frequencies

-  

-   A binary file that contains the results of some frequency
-    analysis, resulting in a 3 dimensional data array 
-   (electrodes  x  frequencies  x  time).

-  

-   There are now two file versions, the first one being obsolete, but 
-   Cartool can still read it. The difference between the two versions is 
-   in the header, the part describing the frequencies.

-  

-   Anyway, for both versions, there is a header, composed of a fixed
-    size part plus a variable size part, then followed by the data 
-   organized as a matrix.

-  

-    

-  

-   1) Header, fixed-size part:
                                        // some strings size
#define     NumFreqTypes                        6
#define     MaxCharFreqType                     32
#define     MaxCharFrequencyName                16
 
                                        // type of content in the file, coded as text
char    FreqTypesNames[ NumFreqTypes ][ MaxCharFreqType ] = {
    "Unknown",
    "FFT Norm",
    "FFT Norm2",
    "FFT Complex",
    "FFT Approximation",
    "S Transform"
    };
 
 
struct  TFreqHeader
{
    int             Version;                // 'FR01' (obsolete) or 'FR02'
    char            Type[MaxCharFreqType];  // of the analysis, and also data stored (see the array FreqTypesNames)
    int             NumChannels;            // total number of electrodes
    int             NumFrequencies;         // saved in file
    int             NumBlocks;              // of repeated analysis, or number of resulting "time frames"
    double          SamplingFrequency;      // of the data in the ORIGINAL file (1000 Hz f.ex.)
    double          BlockFrequency;         // frequency of blocks'occurences (if 1 block is 0.5 s long amd don't overlap -> 2 Hz)
    short           Year;                   // Date of the recording
    short           Month;                  // (can be 00-00-0000 if unknown)
    short           Day;
    short           Hour;                   // Time of the recording
    short           Minute;                 // (can be 00:00:00:0000 if unknown)
    short           Second;
    short           Millisecond;
};

-   2) Header, variable-size part:
// Listing of channels'name
// a matrix of  NumElectrodes * sizeof ( TFreqChannel )  chars
//
// To allow an easy calculation of the data origin,
// be aware that each name ALWAYS take 8 bytes in the header, even if the string length is smaller than that.
// The remaining part is padded with bytes set to 0, f.ex.:
// binary values          70 112 122 00 00 00 00 00 65 70 55 00 00 00 00 00 ...
// string equivalence      F   P   z \0              A  F  7 \0


struct  TFreqChannel
{
    char            ChannelName[8];
};

-   This is the part that differs between file versions 'FR01' and 'FR02'.

-  

-   For the old version 'FR01' :
// Listing of the frequencies actually saved
// size:  NumFrequencies * sizeof ( TFreqFrequency )

struct  TFreqFrequency
{
    double          Frequency;
};

-   For the new version 'FR02' :
// Names assigned to each frequencies or bands actually saved (can be anything)
// size:  NumFrequencies * sizeof ( TFreqFrequencyName )

struct  TFreqFrequencyName
{
    char            FrequencyName[ MaxCharFrequencyName ];
};

-   3) Data part:
// Starting at file position:
//
// for version 'FR01'
//   sizeof ( TFreqHeader ) + NumElectrodes * sizeof ( TFreqChannel ) + NumFrequencies * sizeof ( TFreqFrequency )
//
// for version 'FR02'
//   sizeof ( TFreqHeader ) + NumElectrodes * sizeof ( TFreqChannel ) + NumFrequencies * sizeof ( TFreqFrequencyName )
//
// Data are stored as a matrix  NumTimeFrames x NumElectrodes x NumFrequencies
// in this order: f0 f1 f2 .. fn for first electrode, f0 f1 f2 .. fn for second electrode ... etc  for first  time frame
//          then  f0 f1 f2 .. fn       "       "                            "               "      for second time frame
//                ...etc to the last time frame
//
// Data are of either type
//    float (Little Endian - PC)   for Type == "FFT Norm", "FFT Norm2", "FFT Approximation"
// or complex (classic C/C++ type) for Type == "FFT Complex"

-   .is Inverse Solution matrix

-  

-   A binary file containing the matrix for an Inverse
-    Solution, which has to be subsequently multiplied
-    by the EEG to obtain the final results.

-  

-    

-  

-   Magic number

-  

-   3 formats are currently supported, specified by the magic 
-   number, the first 4 characters in the file:

-  
    
-   
  • 
-   
    
-    'IS01' for a float-type matrix,
    
-   
  • 
-   
    
-    'IS02' for a double-type 
-    matrix (though it is currently converted into float when read by Cartool),
    
-   
  • 
-   
    
-    'IS03' for stacking a set of 
-    float-type matrices, and specifying regularizations.
    
-   

-  

-    

-  

-   ISO1 & ISO2 types

-  

-   Header structure
struct isheader {
    char            magic[ 4 ];         // 'IS01' for float-type matrix, 'IS02' for double-type matrix
    int32           numelectrodes;
    int32           numsolutionpoints;
    int32           numregularizations;
    char            isinversescalar;    // 1 if scalar, 0 if vectorial  (value, and not text)
    } risheader;                        // size 13

-   Matrix structure

-  

-   The matrix can contain either scalar or vectorial results, which 
-   means for each solution point there is either:

-  
    
-   
  • 
-   
    
-    scalar: 1 signed value,
    
-   
  • 
-   
    
-    vectorial: a 3 dimensional vector (a dipole).
    
-   

-  

-    

-  

-   Number of rows of the matrix, is scalar type:
numrows = numsolutionpoints

-   Otherwise, if matrix is of vectorial type, each of the 3 components 
-   of the vectors are written on 3 successive rows, giving:
numrows = 3 * numsolutionpoints

-   Number of columns is always:
numcols = numelectrodes;

-   The matrix is then written row by row:

-   (matrixtype  is either  float  or  double  
-   according to the header field  magic)
matrixtype  matrix [ numrows ][ numcols ];

-    

-  

-   Scalar example, for numrows rows:
s0 s1 s2 ... snumcols-1
s0 s1 s2 ... snumcols-1
...
s0 s1 s2 ... snumcols-1

-   And vectorial example, for numrows rows:
x0 x1 x2 ... xnumcols-1   (for solution point 1, x component)
y0 y1 y2 ... ynumcols-1   (for solution point 1, y component)
z0 z1 z2 ... znumcols-1   (for solution point 1, z component)
x0 x1 x2 ... xnumcols-1   (for solution point 2)
y0 y1 y2 ... ynumcols-1
z0 z1 z2 ... znumcols-1
...
x0 x1 x2 ... xnumcols-1   (for last solution point)
y0 y1 y2 ... ynumcols-1
z0 z1 z2 ... znumcols-1

-    

-  

-   ISO3 type

-  

-   Fixed Header structure
struct isfixedheader {
    char            magic[ 4 ];         // 'IS03'
    int32           numelectrodes;
    int32           numsolutionpoints;
    int32           numregularizations;
    char            isinversescalar;    // 1 if scalar, 0 if vectorial  (value, and not text)
    } risheaderfixed;                   // size 17

-   Note: the number of regularizations has to be >= 1.

-  

-   Variable Header structure

-  

-   Following the fixed header part, the
-    variable header provides the following additional informations:

-  
    
-   
  • 
-   
    
-    electrodes names,
    
-   
  • 
-   
    
-    solution points names,
    
-   
  • 
-   
    
-    the actual values used in the Tikhonov
-     regularizations,
    
-   
  • 
-   
    
-    the display names for each Tikhonov regularizations.
    
-   

-  

-    
typedef char        TElectrodeName     [ 32 ]; // 1 electrode name
typedef char        TSolutionPointName [ 16 ]; // 1 solution point name
typedef char        TRegularizationName[ 32 ]; // 1 regularization name
 
 
struct isheadervariable {
    TElectrodeName      ElectrodesNames      [ NumElectrodes      ];
    TSolutionPointName  SolutionPointsNames  [ NumSolutionPoints  ];
                                double              RegularizationValues [ NumRegularizations ];
    TRegularizationName RegularizationNames  [ NumRegularizations ];
    } risheadervariable; 

-   Matrix structure

-  

-   The matrix content is the same as for type 'IS01' 
-   (float matrix), simply repeated by the number of regularizations:
float               Matrices[ NumRegularizations ][ NumRows ][ NumColumns ];

-   .lf Lead Field file

-  

-   A simple binary file format to store a vectorial
-    Lead Field, in double precision.

-  

-    

-  

-   It has a short header:
struct lfheader {
    int32   number_of_electrodes;
    int32   number_of_solution_points;
    } lfheader;                         // size 8

-   Then followed by the data, in double precision, with this 
-   ordering (multiplexing the (x,y,z) components):
x0 y0 z0  x1 y1 z1  x2 y2 z2 ... xnumcols-1 ynumcols-1 znumcols-1   (for electrode number 1)
x0 y0 z0  x1 y1 z1  x2 y2 z2 ... xnumcols-1 ynumcols-1 znumcols-1   (for electrode number 2)
...
x0 y0 z0  x1 y1 z1  x2 y2 z2 ... xnumcols-1 ynumcols-1 znumcols-1   (for last electrode)

-   Or represented as a C array:
double              LeadField[ number_of_electrodes ][ number_of_solution_points ][ 3 ];

-   .lm Link Many file

-  

-   A text file containing a list of many files that have been 
-   linked by the user. The linked files have to be in whatsoever way 
-   related, though this is very versatile and open to new definitions.

-   Putting together files will allow to share their informations 
-   between them all, for example an Eeg linked with some electrodes 
-   coordinates will give to the Eeg the electrodes names and 3D positions.

-   The definate advantage from the link is that, depending on the files 
-   linked, new functionnalities are offered to the user through 
-   new type of views. Taking the same 
-   example, it brings a view showing the potential displayed as a map.

-  

-   See here for more explanations.

-  

-   The .lm file is simply a list of other files, written with 
-   their full path. F.ex.:
D:\Data\avebrain\egi125.xyz
D:\Data\avebrain\myeeg.condition1.eph
D:\Data\avebrain\myeeg.condition2.eph

-   .mrk Marker file

-  

-   Contains the markers defined by the user.

-  

-   There are 2 formats for .mrk file, the first being in binary 
-   form (obsolete format), the second being in textual form, and 
-   the one actually used as it can be easily read and modified by the user.

-   In any cases, the markers must be written ordered, sorted 
-   first on their starting positions then on their ending positions (if 
-   two markers have equal starting positions).

-   It is not advised to write duplicate markers with 
-   exactly the same starting and ending positions. Cartool can read 
-   them, can display them as superimposed markers, but you can expect 
-   unpredictable results when it comes to computing (like averaging, 
-   exporting, etc...). So don't.

-  

-    

-  

-   Text format:

-  

-   A first line with this characters as a magic number:
TL02

-   Then as many text lines as needed, structured this way:
starting position     ending position    "description text in quote"

-   Note: the current limit for the description text is 31 chars.

-  

-    

-  

-   Binary format (obsolete):

-  

-   A header followed by a list of markers, all in binary. The file 
-   header structure is:
struct mrkheader {
    char magic[4];                      // always 'TL01'
    } mrkheader;                        // size 4

-    

-  

-   And the format for a single marker is:
struct onemrk {
    long   Position;                    // from this TF
    long   To;                          // to this TF
    ushort Code;                        // trigger code
    ushort Type;                        // should always be 0x2 for a marker
    ushort Dummy;                       // not used, for the user
    char   Name[6];                     // name of the tag
    } onemrk;                           // size 20

-   .mtg Montage file

-  

-   A text file that defines a montage to be used with the EEG
-    display (it has to be created in any text editor, Cartool does 
-   not provide an editor for this task).

-  

-    

-  

-   Format:

-  

-   Always a first line with these characters as magic number:
MT01

-   Then, each following lines can independently be any of these three formats:
el
el1   el2
el1   el2   name

-   In the first case, the value of the electrode el 
-   (the name of the electrode) is taken as is.

-   In the second case, the value is the result of subtracting el2 
-   to el1.

-   The last case is the same as the second one, but a name is given to 
-   override the default one (which would be  el1-el2).
-    This name must be written "as is", without quotes nor spaces.

-  

-   Non-compliant lines (more fields, empty lines, unknown electrode 
-   names..) are simply ignored.

-  

-   You can put whatever you want in this file, repeating electrodes, 
-   changing their order, including auxiliaries
-    or computed tracks. The only limit is that the number of lines 
-   should not be more than the number of electrodes in the original file.

-  

-    

-  

-   Example:
MT01
1     2
2     3
3     4
4     5
Aux1  Aux2  DiffAux
10
9
8
7
6
5
4
3
2
1

-   .rois Regions Of Interest

-  

-   This text file contains the required structural informations 
-   to apply regions of interest calculus on data. At the moment, it 
-   simply holds groups of indexes (of electrodes / solution points). You 
-   may not be interested on the actual file format, but rather on how to create
-    the ROIs in Cartool, or how to make use 
-   of them?

-  

-   First line, the magic number to indicate that the content is about 
-   indexes (as opposite to voxels):
RO01

-   Next 2 lines:
Dimension_of_original_data
Number_of_rois

-   What is meant by  Dimension_of_original_data 
-    is simply the number of electrodes (or solution points) of  the 
-   original data the rois were made from. This is used only for checking 
-   you're not going to apply the .rois file to the wrong data, which 
-   usually have different dimensions.

-  

-   Then follows 2 lines for each roi:
Roi_name
List_of_indexes

-   The name of the roi could be anything on the line, including spaces. 
-   Quotes are not needed.

-  

-   Within the list of indexes, use a space to separate between each 
-   index. The end of line means the end of the list. Simple. And BTW, indexes
-    start from 1, not 0.

-  

-    

-  

-   Example made from a setup of 125 electrodes, into 4 rois:
RO01
125
4
Front Left
26 22 33 23 18 27 24 19 44 39 34 28 25 20 49 45 40 35 29 21 12 41 36 30 13 7 46 37 31
Front Right
14 8 15 9 1 10 3 2 4 124 123 122 121 120 5 119 118 117 116 113 112 111 110 115 114 107 106 105 109
Back Left
42 47 48 43 38 32 50 51 52 53 54 56 57 58 59 60 61 67 63 64 65 66 72 70 71 69 75 74
Back Right
81 88 104 80 87 94 99 103 79 86 93 98 102 78 92 97 101 77 85 91 96 108 84 100 83 90 89 95

-   .ris Results of Inverse Solution computation

-  

-   This binary file is the final result of inverse solution 
-   computations, after the matrix has been multiplied by the Eeg. It is 
-   made of a header followed by a matrix of floats.

-  

-    

-  

-   Header structure
struct risheader {
    char  magic[4];                      // always 'RI01'
    int32 numsolutionpoints;
    int32 numtimeframes;
    float samplingfrequency;             // in Herz
    char  isinversescalar;               // 1 if scalar, 0 if vectorial  (value, and not text)
    } risheader;                         // size 17

-    

-  

-   Matrix structure

-  

-   Number of rows:
numrows = numtimeframes;

-   If the matrix contains scalar results, the number of columns is
numcols = numsolutionpoints;

-   If the matrix contains vectorial results, a 3-uple (x,y,z) is 
-   written, and the number of columns is
numcols = 3 * numsolutionpoints;

-   The matrix is then written row by row:
float matrix [ numrows ][ numcols ];

-    

-  

-   Scalar example, for numrows rows:
s0 s1 s2 ... snumcols-1
s0 s1 s2 ... snumcols-1
...
s0 s1 s2 ... snumcols-1

-   And vectorial example, for numrows rows:
x0 y0 z0  x1 y1 z1 ... xnumcols-1 ynumcols-1 znumcols-1
x0 y0 z0  x1 y1 z1 ... xnumcols-1 ynumcols-1 znumcols-1
...
x0 y0 z0  x1 y1 z1 ... xnumcols-1 ynumcols-1 znumcols-1

-   .sef Simple Eeg Format

-  

-   Simple (or safe, or stupid) binary format containing the 
-   minimal data structure to describe correctly an EEG, either an 
-   original recording or an ERP. It has a header, made of a fixed part 
-   and a variable part, followed by the calibrated data (in micro-volts).

-  

-    

-  

-   Fixed part of the header:
struct  TSefHeader
{
    int   Version;                       // magic number filled with the wide char 'SE01'
    int   NumElectrodes;                 // total number of electrodes
    int   NumAuxElectrodes;              //  out of which are auxiliaries
    int   NumTimeFrames;                 // time length
    float SamplingFrequency;             // frequency in Hertz
    short Year;                          // Date of the recording
    short Month;                         // (set to 00-00-0000 if unknown)
    short Day;
    short Hour;                          // Time of the recording
    short Minute;                        // (set to 00:00:00:0000 if unknown)
    short Second;
    short Millisecond;
};

-    

-  

-   Variable part of the header:

-  

-   The names of the channels, as a matrix of  NumElectrodes 
-   x 8 chars.
typedef char        TSefChannelName[8];  // 1 electrode name

-    

-  

-   To allow an easy calculation of the data origin, be aware that names 
-   are always stored on 8 bytes, even if the string length is 
-   smaller than that. In this case, the remaining part is padded with 
-   bytes set to 0, f.ex. two consecutive names:

-  

-   binary 
-   values           
-    70 112 122 00 00 00 00 00 65 70 55 00 00 00 00 00 ...

-  

-   string equivalence      F   
-   P     z    
-   \0                     
-    A  F   7   \0

-  

-    

-  

-   Data part:

-  

-   Starting at file position:
sizeof ( TSefHeader ) + 8 * NumElectrodes

-   data are stored as a float (Little Endian convention - PC) matrix 
-   written row by row:
float data [ NumTimeFrames ][ NumElectrodes ];

-   .seg Segmentation

-  

-   A text file used to store and display the results of the segmentation
-    process.

-  

-   First two lines is the header:
number_of_clusters   number_of_files   number_of_time_frames
number_of_tracks   tracks_name1  tracks_name2  ...  tracks_namen

-   where

-  

-   number_of_clusters    is the number of clusters from 
-   the segmentation process

-   number_of_files       is the number of 
-   files that have been segmented together

-   number_of_time_frames is the number of time frames of each segmented file

-   number_of_tracks      is the number of 
-   informations saved for each file (f.ex. 5 for  Gfp Dis Seg GEV EV)

-   tracks_namei         
-    is the name of the ith track (f.ex. "Gfp")

-  

-    

-  

-   Then follow the data, one line per time frame (as in .eph 
-   file). Each line concatenates the  number_of_tracks  
-   variables, one file after the other, f.ex.:
File1Gfp  File1Dis  File1Seg  File1GEV  File2Gfp  File2Dis  File2Seg  File2GEV ... FilenGfp  FilenDis  FilenSeg  FilenGEV

-   .spi Solution Points Irregularly spaced

-  

-   A text file consisting of a list of 3D points, used as 
-   the solution points for the inverse solutions.
-    These points can be irregularly spaced, and don't need to be 
-   on any sort of a grid.

-  

-    

-   There is no header, and each line simply contains the coordinates 
-   of one point (floatting points values), and an optional name 
-   (max 15 characters):
x   y   z   optionalname

-   .spr Solution Points in Regular grid (obsolete)

-  

-   Same format as .spi, but the points 
-   have to be regularly spaced. That is, there has to be the same 
-   distance (usually an integer value) between neighbors, and for all coordinates.

-  

-   .tva Trigger VAlidation file

-  

-   A text file that stores if a trigger was right or wrong, f.ex. 
-   the choices a subject replied during an experiment.

-   There are two slightly different versions of this file, the 
-   difference being rather semantic than on the format itself:

-    

-  

-   Version 1

-  

-   Is a file without header, containing a serie of lines which 
-   have the following format:
accepted   reaction_time   trigger_code

-   where:

-  

-   accepted               
-    is either 0 (wrong answer / false) or 1 (correct 
-   answer / true)

-   reaction_time  
-    is the reaction time of the answer, in milliseconds, 0 otherwise

-   trigger_code     
-    is the name of the trigger

-    

-  

-   Version 2

-  

-   Is a serie of lines identical to version 1, but the file starts with
-    the header:
TV01

-    

-  

-   The difference between the two versions consist in which triggers are 
-   being listed.

-  

-   Version 1 is usually the ouput of the stimulation program,
-    all triggers of the experiment are therefore listed. 
-   So if there are three triggers A, B, C repeated 100 times each, we 
-   will have 300 lines in the file.

-  

-   Version 2 is rather an output from Cartool itself, 
-   usually from the averaging process. It 
-   will list only the triggers that were considered during 
-   the processing. If only triggers A and B were used, we will have only 
-   200 + 1 lines in the file, the C trigger being ignored. These tva 
-   files can be used to re-do the averaging.

-  

-    

-  

-   Example of version 1:
1 1765  45
1 977.1 43
1 1191  36
0 0     56
0 0     35
1 1309  55
1 1696  49
1 1211  33
...

-   Example of version 2:
TV01
1 0 On
1 0 Off
0 0 On
1 0 Off
1 0 On
0 0 Off
...

-   .vrb Verbose file

-  

-   A text file generated during the main
-    processings of Cartool. It records all the parameters set for 
-   the processings and in some case the user's responses during the 
-   procedure. These files are generated just for your convenience, to 
-   help you store and recover how you computed that incredible files of yours!

-  

-   .xyz Electrodes coordinates for head

-  

-   A text file containing a list of electrodes coordinates on a 
-   scalp. For more advanced electrodes setup (strips, clusters of 
-   electrodes, grids...) see the .els format.

-  

-   First line (though the radius of the cluster is not used anymore in Cartool):
Number_of_electrodes  Radius_of_the_cluster

-   Then a list of coordinates, one per line:
x   y   z   label

-   Example:
   29    1
  9.510565E-0001 -3.090170E-0001 -0.000000E+0000 Fp2
  6.590572E-0001 -5.336940E-0001  5.299193E-0001 F4
  7.531501E-0020 -6.946584E-0001  7.193398E-0001 C4
 -6.590572E-0001 -5.336940E-0001  5.299193E-0001 P4
 -9.510565E-0001 -3.090170E-0001 -0.000000E+0000 O2
  5.877853E-0001 -8.090170E-0001 -0.000000E+0000 F8
  1.084202E-0019 -1.000000E+0000 -0.000000E+0000 T4
 -5.877853E-0001 -8.090170E-0001 -0.000000E+0000 T6
  8.619499E-0001 -4.019339E-0001  3.090170E-0001 AF4
  3.367557E-0001 -8.772786E-0001  3.420201E-0001 FC6
  3.535534E-0001 -3.535534E-0001  8.660254E-0001 FC2
 -3.535534E-0001 -3.535534E-0001  8.660254E-0001 CP2
 -3.367557E-0001 -8.772786E-0001  3.420201E-0001 CP6
  9.510565E-0001  3.090170E-0001 -0.000000E+0000 Fp1
  6.590572E-0001  5.336940E-0001  5.299193E-0001 F3
 -0.000000E+0000  6.946584E-0001  7.193398E-0001 C3
 -6.590572E-0001  5.336940E-0001  5.299193E-0001 P3
 -9.510565E-0001  3.090170E-0001 -0.000000E+0000 O1
  5.877853E-0001  8.090170E-0001 -0.000000E+0000 F7
 -0.000000E+0000  1.000000E+0000 -0.000000E+0000 T3
 -5.877853E-0001  8.090170E-0001 -0.000000E+0000 T5
  8.619499E-0001  4.019339E-0001  3.090170E-0001 AF3
  3.367557E-0001  8.772786E-0001  3.420201E-0001 FC5
  3.535534E-0001  3.535534E-0001  8.660254E-0001 FC1
 -3.535534E-0001  3.535534E-0001  8.660254E-0001 CP1
 -3.367557E-0001  8.772786E-0001  3.420201E-0001 CP5
  6.946584E-0001  0.000000E+0000  7.193398E-0001 Fz
  0               0               1              Cz
 -6.946584E-0001 -0.000000E+0000  7.193398E-0001 Pz

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    
+ 
+     

+         

+             Appendix C

+             Cartool File Formats
+         

+         

+              
+         

+         

+             
+         

+         

+             
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+             

+                         

+                             .csv
+                     

+                         

+                             Comma Separated Values
+                     

+                         

+                             .data
+                     

+                         

+                             Data array
+                     

+                         

+                             .els
+                     

+                         

+                             ELectrodes Setup (complex cases)
+                     

+                         

+                             .ep
+                     

+                         

+                             Evoked Potentials
+                     

+                         

+                             .eph
+                     

+                         

+                             Evoked Potentials with Header
+                     

+                         

+                             .epsd
+                         

+                         

+                             .epse
+                     

+                         

+                             Evoked Potentials Standard Deviation / Standard Error
+                     

+                         

+                             .freq
+                     

+                         

+                             Frequencies
+                     

+                         

+                             .is
+                     

+                         

+                             Inverse Solution matrix
+                     

+                         

+                             .lf
+                     

+                         

+                             Lead Field file
+                     

+                         

+                             .lm
+                     

+                         

+                             Link Many file
+                     

+                         

+                             .mrk
+                     

+                         

+                             Marker file
+                     

+                         

+                             .mtg
+                     

+                         

+                             Montage file
+                     

+                         

+                             .ris
+                     

+                         

+                             Results of Inverse Solution computation
+                     

+                         

+                             .rois
+                     

+                         

+                             Regions Of Interest
+                     

+                         

+                             .sef
+                     

+                         

+                             Simple Eeg Format
+                     

+                         

+                             .seg
+                     

+                         

+                             Segmentation
+                     

+                         

+                             .spi
+                     

+                         

+                             Solution Points Irregularly spaced
+                     

+                         

+                             .spr
+                     

+                         

+                             Solution Points on Regular grid (obsolete)
+                     

+                         

+                             .tva
+                     

+                         

+                             Trigger VAlidation file
+                     

+                         

+                             .vrb
+                     

+                         

+                             Verbose file
+                     

+                         

+                             .xyz
+                     

+                         

+                             Electrodes coordinates (simpler case)
+                     

+         

+         

+             .csv Comma Separated Values
+         

+         

+             This is not a format defined by Cartool, but a very handy and 
+                 well-recognized
+                 file format
+              to store an array of values (handled direclty
+             by Excel, Statistica, Cartool...)
+         

+         

+              
+         

+         

+             Basically, it is a text file with values on each line being
+             separated either by a comma (,) or by a semi-colon (;),
+             according to your language settings (just to make simple things
+             already complicated... but Cartool will gracefully read both). You
+             can open them either with a text editor, or directly as a spreadsheet
+             in Excel, Statistica, etc... (Note that Cartool also works with its
+             equivalent 
+                 Tab
+                 Separated text file format
+             )
+         

+         

+              
+         

+         

+             If you have problems and/or want to change the way Cartool, Excel or
+             all other programs behave, do the following:
+         

+         
    
+             
  • 
+                 
    
+                      go to the Control Panel, choose "Regional & Language Options"
    
+             
  • Click on "Customize"
    
+             
  • 
+                 Change "List Separator" to force it to
+                 the character you prefer, but I recommend either a comma (,)
+                 or a semi-colon (;).
    
+         

+         

+              
+         

+         

+             The content organization done by Cartool is the following:
+         

+         
    
+             
  • 
+                 
    
+                     A first line which gives the names of the variables,
+                     and their sequence.
    
+             
  • 
+                 Then each following lines contains the data
+                 themselves, with exactly the same number and same sequence of variables
+                 as the first line (padding with separators if needed).
    
+             
  • 
+                 Two files with the same variable names but set in a 
+                     different
+                     order are equivalent
+                 ., so you can import results / parameters
+                 from other programs quite easily.
    
+         

+         

+              
+         

+         

+             Just an example to make it clear, a file used to hold the files
+             parameters for the averaging process:
+         
file;session;tva;triggers
E:\Data\Eeg1.eph;1;;1 2 3 4
E:\Data\Eeg1.eph;2;;5 6 7 8
E:\Data\Eeg2.eph;;;1 2 3 4 5 6 7 8

+             The first line enumerates the 4 variables (file, session etc...), and
+             there are 3 lines of data with some of these variables defined, and
+             some undefined.
+         

+         

+             The order of the variables does not matter, and it could have be
+             written as, f.ex.:
+         
file;triggers;session;tva
E:\Data\Eeg1.eph;1 2 3 4;1;
E:\Data\Eeg1.eph;5 6 7 8;2;
E:\Data\Eeg2.eph;1 2 3 4 5 6 7 8;;

+             .data Data array
+         

+         

+             A text file used to store and display any kind of
+             informations, used for example in the 
+                 segmentation
+                 process
+             .

+             It is a variant of the .seg format, please refer
+             to it for the full explanations.
+         

+         

+             The only difference is in the header (first two lines) which lacks
+             the  number_of_clusters  variable:
+         
number_of_files   number_of_time_frames
number_of_tracks   tracks_name1  tracks_name2  ...  tracks_namen

+             .els ELectrodes Setup
+         

+         

+             A text file describing a setup of electrodes. It allows
+             separate clusters of electrodes (for example 2 grids, or a few
+             strips, or electrodes on the scalp plus some auxiliaries...), and
+             each one of the clusters can be of a different type. Another (and
+             obsolete) format is the .xyz.
+         

+         

+             First line, a magic number:
+         
ES01

+             Next 2 lines:
+         
Total_number_of_electrodes
Number_of_clusters

+             Now repeat for each cluster (at least 1):
+         
Cluster_name
Cluster_number_of_electrodes
Cluster_type

+             Cluster_type  could be seen as the dimensionality of the cluster:
+         

+         
    
+             
  • 
+                 
    
+                     0 for separated electrodes (like auxiliaries), or "points"
    
+             
  • 1 for a strip of electrodes, or "line"
    
+             
  • 2 for a grid of electrodes, or "array"
    
+             
  • 
+                 3 for a 3D set of electrodes, usually
+                 on the scalp, that will be fitted by a 2D Delaunay triangulation
+                 surface (but in 3D...).
    
+         

+         

+             Then the list of coordinates, one per line:
+         
x   y   z   label   optional_flag

+             x, y, z  are, of course, the coordinates, and label the name of
+             the electrode. optional_flag can either be missing or be the
+             identifier Bad, in which case it indicates that the electrodes
+             has a non-significative signal (broken electrode, noisy signal,
+             etc...), and though it will be geometrically used with its neighbors
+             in the building of the 3D tesselation, the value of its signal will
+             not appear to avoid spoiling the display.
+         

+         

+              
+         

+         

+             The idea of clustering electrodes is to isolate the interpolations
+             between electrodes, so that different clusters won't interfere
+             graphically. For example you can disjoin the auxiliaries electrodes,
+             as you don't want to see them interpolated with regular Eeg.
+         

+         

+             If two, or more, 3D clusters share the very same name, they will be
+             merged into a single, big cluster of the same name. Still in the case
+             some auxiliaries electrodes were recorded in the middle of regular
+             electrodes, there are, say 3 clusters: 3D, auxs, 3D again, so the
+             program understands that both 3D clusters are the same. If you don't
+             want this merging, simply change the names!
+         

+         

+              
+         

+         

+             Example:
+         
ES01
41
1
10-10 System
41
3
  1.000000E+0000  0.000000E+0000 -0.000000E+0000 Fpz
  8.090170E-0001  5.877853E-0001 -0.000000E+0000 AF7
  9.205049E-0001  0.000000E+0000  3.907311E-0001 AFz
  8.090170E-0001 -5.877853E-0001 -0.000000E+0000 AF8
  6.273924E-0001  7.217324E-0001  2.923717E-0001 F5
  6.590572E-0001  5.336940E-0001  5.299193E-0001 F3
  6.946584E-0001  0.000000E+0000  7.193398E-0001 Fz
  6.590572E-0001 -5.336940E-0001  5.299193E-0001 F4
  6.273924E-0001 -7.217324E-0001  2.923717E-0001 F6
  3.090170E-0001  9.510565E-0001 -0.000000E+0000 FT7
  3.367557E-0001  8.772786E-0001  3.420201E-0001 FC5
  3.535534E-0001  3.535534E-0001  8.660254E-0001 FC1
  3.583679E-0001  0.000000E+0000  9.335804E-0001 FCz
  3.535534E-0001 -3.535534E-0001  8.660254E-0001 FC2
  3.367557E-0001 -8.772786E-0001  3.420201E-0001 FC6
  3.090170E-0001 -9.510565E-0001 -0.000000E+0000 FT8
 -0.000000E+0000  1.000000E+0000 -0.000000E+0000 T3
 -0.000000E+0000  6.946584E-0001  7.193398E-0001 C3
 -0.000000E+0000  3.583679E-0001  9.335804E-0001 C1
  0               0               1              Cz
  3.885433E-0020 -3.583679E-0001  9.335804E-0001 C2
  7.531501E-0020 -6.946584E-0001  7.193398E-0001 C4
  1.084202E-0019 -1.000000E+0000 -0.000000E+0000 T4
 -3.090170E-0001  9.510565E-0001 -0.000000E+0000 TP7
 -3.367557E-0001  8.772786E-0001  3.420201E-0001 CP5
 -3.535534E-0001  3.535534E-0001  8.660254E-0001 CP1
 -3.583679E-0001 -0.000000E+0000  9.335804E-0001 CPz
 -3.535534E-0001 -3.535534E-0001  8.660254E-0001 CP2
 -3.367557E-0001 -8.772786E-0001  3.420201E-0001 CP6
 -3.090170E-0001 -9.510565E-0001 -0.000000E+0000 TP8
 -6.273924E-0001  7.217324E-0001  2.923717E-0001 P5
 -6.590572E-0001  5.336940E-0001  5.299193E-0001 P3
 -6.946584E-0001 -0.000000E+0000  7.193398E-0001 Pz
 -6.590572E-0001 -5.336940E-0001  5.299193E-0001 P4
 -6.273924E-0001 -7.217324E-0001  2.923717E-0001 P6
 -8.090170E-0001  5.877853E-0001 -0.000000E+0000 PO7
 -8.619499E-0001  4.019339E-0001  3.090170E-0001 PO3
 -9.205049E-0001 -0.000000E+0000  3.907311E-0001 POz
 -8.619499E-0001 -4.019339E-0001  3.090170E-0001 PO4
 -8.090170E-0001 -5.877853E-0001 -0.000000E+0000 PO8
 -1.000000E+0000 -0.000000E+0000 -0.000000E+0000 Oz

+             .ep Evoked Potentials
+         

+         

+             A very basic text file format to store an ERP, without header.
+             This is a simple matrix of values, each line (with end-of-line)
+             having all the electrodes values for a given time frame:
+         
electrode_1 electrode_2 electrode_3 ... electrode_n

+             Lines are repeated for each time frames (the number of time frames is
+             therefore the number of lines). Cartool calculates the number of
+             electrodes and the number of time frames by scanning the whole file
+             at opening time. But it can not guess the sampling frequency, until
+             the user specify it.
+         

+         

+             .eph Evoked Potentials with Header
+         

+         

+             A very basic text file format to store an ERP, with a small header.
+         

+         

+             The first line is the header:
+         
number_of_electrodes   number_of_time_frames   sampling_frequency

+             It is followed by the same block as in the .ep
+             files. Cartool does not scan the whole file to get the number of
+             electrodes etc... as they are read (and trusted) directly from the
+             first line.
+         

+         

+             .epsd  and  .epse 
+             Evoked Potentials Standard Deviation / Standard Error
+         

+         

+             Actually, the format is just the same as the .eph one.
+         

+         

+             It simply holds the Standard Deviation / Standard Error of an averaged file.
+         

+         

+             .freq Frequencies
+         

+         

+             A binary file that contains the results of some 
+                 frequency
+                 analysis
+             , resulting in a 3 dimensional data array
+             (electrodes  x  frequencies  x  time).
+         

+         

+             There are now two file versions, the first one being obsolete, but
+             Cartool can still read it. The difference between the two versions is
+             in the header, the part describing the frequencies.
+         

+         

+             Anyway, for both versions, there is a header, composed of a 
+                 fixed
+                 size part
+              plus a variable size part, then followed by the data
+             organized as a matrix.
+         

+         

+              
+         

+         

+             1) Header, fixed-size part:
+         
                                        // some strings size
#define     NumFreqTypes                        6
#define     MaxCharFreqType                     32
#define     MaxCharFrequencyName                16
 
                                        // type of content in the file, coded as text
char    FreqTypesNames[ NumFreqTypes ][ MaxCharFreqType ] = {
    "Unknown",
    "FFT Norm",
    "FFT Norm2",
    "FFT Complex",
    "FFT Approximation",
    "S Transform"
    };
 
 
struct  TFreqHeader
{
    int             Version;                // 'FR01' (obsolete) or 'FR02'
    char            Type[MaxCharFreqType];  // of the analysis, and also data stored (see the array FreqTypesNames)
    int             NumChannels;            // total number of electrodes
    int             NumFrequencies;         // saved in file
    int             NumBlocks;              // of repeated analysis, or number of resulting "time frames"
    double          SamplingFrequency;      // of the data in the ORIGINAL file (1000 Hz f.ex.)
    double          BlockFrequency;         // frequency of blocks'occurences (if 1 block is 0.5 s long amd don't overlap -> 2 Hz)
    short           Year;                   // Date of the recording
    short           Month;                  // (can be 00-00-0000 if unknown)
    short           Day;
    short           Hour;                   // Time of the recording
    short           Minute;                 // (can be 00:00:00:0000 if unknown)
    short           Second;
    short           Millisecond;
};

+             2) Header, variable-size part:
+         
// Listing of channels'name
// a matrix of  NumElectrodes * sizeof ( TFreqChannel )  chars
//
// To allow an easy calculation of the data origin,
// be aware that each name ALWAYS take 8 bytes in the header, even if the string length is smaller than that.
// The remaining part is padded with bytes set to 0, f.ex.:
// binary values          70 112 122 00 00 00 00 00 65 70 55 00 00 00 00 00 ...
// string equivalence      F   P   z \0              A  F  7 \0


struct  TFreqChannel
{
    char            ChannelName[8];
};

+             This is the part that differs between file versions 'FR01' and 'FR02'.
+         

+         

+             For the old version 'FR01' :
+         
// Listing of the frequencies actually saved
// size:  NumFrequencies * sizeof ( TFreqFrequency )

struct  TFreqFrequency
{
    double          Frequency;
};

+             For the new version 'FR02' :
+         
// Names assigned to each frequencies or bands actually saved (can be anything)
// size:  NumFrequencies * sizeof ( TFreqFrequencyName )

struct  TFreqFrequencyName
{
    char            FrequencyName[ MaxCharFrequencyName ];
};

+             3) Data part:
+         
// Starting at file position:
//
// for version 'FR01'
//   sizeof ( TFreqHeader ) + NumElectrodes * sizeof ( TFreqChannel ) + NumFrequencies * sizeof ( TFreqFrequency )
//
// for version 'FR02'
//   sizeof ( TFreqHeader ) + NumElectrodes * sizeof ( TFreqChannel ) + NumFrequencies * sizeof ( TFreqFrequencyName )
//
// Data are stored as a matrix  NumTimeFrames x NumElectrodes x NumFrequencies
// in this order: f0 f1 f2 .. fn for first electrode, f0 f1 f2 .. fn for second electrode ... etc  for first  time frame
//          then  f0 f1 f2 .. fn       "       "                            "               "      for second time frame
//                ...etc to the last time frame
//
// Data are of either type
//    float (Little Endian - PC)   for Type == "FFT Norm", "FFT Norm2", "FFT Approximation"
// or complex (classic C/C++ type) for Type == "FFT Complex"

+             .is Inverse Solution matrix
+         

+         

+             A binary file containing the matrix for an 
+                 Inverse
+                 Solution
+             , which has to be subsequently 
+                 multiplied
+                 by the EEG
+              to obtain the final results.
+         

+         

+              
+         

+         

+             Magic number
+         

+         

+             3 formats are currently supported, specified by the magic
+             number, the first 4 characters in the file:
+         

+         
    
+             
  • 
+                 
    
+                     'IS01' for a float-type matrix,
+                 
    
+             
  • 
+                 
    
+                     'IS02' for a double-type
+                     matrix (though it is currently converted into float when read by Cartool),
+                 
    
+             
  • 
+                 
    
+                     'IS03' for stacking a 
+                         set of
+                         float-type matrices
+                     , and specifying regularizations.
+                 
    
+         

+         

+              
+         

+         

+             ISO1 & ISO2 types
+         

+         

+             Header structure
+         
struct isheader {
    char            magic[ 4 ];         // 'IS01' for float-type matrix, 'IS02' for double-type matrix
    int32           numelectrodes;
    int32           numsolutionpoints;
    int32           numregularizations;
    char            isinversescalar;    // 1 if scalar, 0 if vectorial  (value, and not text)
    } risheader;                        // size 13

+             Matrix structure
+         

+         

+             The matrix can contain either scalar or vectorial results, which
+             means for each solution point there is either:
+         

+         
    
+             
  • 
+                 
    
+                     scalar: 1 signed value,
+                 
    
+             
  • 
+                 
    
+                     vectorial: a 3 dimensional vector (a dipole).
+                 
    
+         

+         

+              
+         

+         

+             Number of rows of the matrix, is scalar type:
+         
numrows = numsolutionpoints

+             Otherwise, if matrix is of vectorial type, each of the 3 components
+             of the vectors are written on 3 successive rows, giving:
+         
numrows = 3 * numsolutionpoints

+             Number of columns is always:
+         
numcols = numelectrodes;

+             The matrix is then written row by row:

+             (matrixtype  is either  float  or  double 
+             according to the header field  magic)
+         
matrixtype  matrix [ numrows ][ numcols ];

+              
+         

+         

+             Scalar example, for numrows rows:
+         
s0 s1 s2 ... snumcols-1
s0 s1 s2 ... snumcols-1
...
s0 s1 s2 ... snumcols-1

+             And vectorial example, for numrows rows:
+         
x0 x1 x2 ... xnumcols-1   (for solution point 1, x component)
y0 y1 y2 ... ynumcols-1   (for solution point 1, y component)
z0 z1 z2 ... znumcols-1   (for solution point 1, z component)
x0 x1 x2 ... xnumcols-1   (for solution point 2)
y0 y1 y2 ... ynumcols-1
z0 z1 z2 ... znumcols-1
...
x0 x1 x2 ... xnumcols-1   (for last solution point)
y0 y1 y2 ... ynumcols-1
z0 z1 z2 ... znumcols-1

+              
+         

+         

+             ISO3 type
+         

+         

+             Fixed Header structure
+         
struct isfixedheader {
    char            magic[ 4 ];         // 'IS03'
    int32           numelectrodes;
    int32           numsolutionpoints;
    int32           numregularizations;
    char            isinversescalar;    // 1 if scalar, 0 if vectorial  (value, and not text)
    } risheaderfixed;                   // size 17

+             Note: the number of regularizations has to be >= 1.
+         

+         

+             Variable Header structure
+         

+         

+             Following the fixed header part, the
+             variable header provides the following additional informations:
+         

+         
    
+             
  • 
+                 
    
+                     electrodes names,
+                 
    
+             
  • 
+                 
    
+                     solution points names,
+                 
    
+             
  • 
+                 
    
+                     the actual values used in the 
+                         Tikhonov
+                         regularizations
+                     ,
+                 
    
+             
  • 
+                 
    
+                     the display names for each Tikhonov regularizations.
+                 
    
+         

+         

+              
+         
typedef char        TElectrodeName     [ 32 ]; // 1 electrode name
typedef char        TSolutionPointName [ 16 ]; // 1 solution point name
typedef char        TRegularizationName[ 32 ]; // 1 regularization name
 
 
struct isheadervariable {
    TElectrodeName      ElectrodesNames      [ NumElectrodes      ];
    TSolutionPointName  SolutionPointsNames  [ NumSolutionPoints  ];
                                double              RegularizationValues [ NumRegularizations ];
    TRegularizationName RegularizationNames  [ NumRegularizations ];
    } risheadervariable; 

+             Matrix structure
+         

+         

+             The matrix content is the same as for type 'IS01'
+             (float matrix), simply repeated by the number of regularizations:
+         
float               Matrices[ NumRegularizations ][ NumRows ][ NumColumns ];

+             .lf Lead Field file
+         

+         

+             A simple binary file format to store a 
+                 vectorial
+                 Lead Field
+             , in double precision.
+         

+         

+              
+         

+         

+             It has a short header:
+         
struct lfheader {
    int32   number_of_electrodes;
    int32   number_of_solution_points;
    } lfheader;                         // size 8

+             Then followed by the data, in double precision, with this
+             ordering (multiplexing the (x,y,z) components):
+         
x0 y0 z0  x1 y1 z1  x2 y2 z2 ... xnumcols-1 ynumcols-1 znumcols-1   (for electrode number 1)
x0 y0 z0  x1 y1 z1  x2 y2 z2 ... xnumcols-1 ynumcols-1 znumcols-1   (for electrode number 2)
...
x0 y0 z0  x1 y1 z1  x2 y2 z2 ... xnumcols-1 ynumcols-1 znumcols-1   (for last electrode)

+             Or represented as a C array:
+         
double              LeadField[ number_of_electrodes ][ number_of_solution_points ][ 3 ];

+             .lm Link Many file
+         

+         

+             A text file containing a list of many files that have been
+             linked by the user. The linked files have to be in whatsoever way
+             related, though this is very versatile and open to new definitions.

+             Putting together files will allow to share their informations
+             between them all, for example an Eeg linked with some electrodes
+             coordinates will give to the Eeg the electrodes names and 3D positions.

+             The definate advantage from the link is that, depending on the files
+             linked, new functionnalities are offered to the user through
+             new type of views. Taking the same
+             example, it brings a view showing the potential displayed as a map.
+         

+         

+             See here for more explanations.
+         

+         

+             The .lm file is simply a list of other files, written with
+             their full path. F.ex.:
+         
D:\Data\avebrain\egi125.xyz
D:\Data\avebrain\myeeg.condition1.eph
D:\Data\avebrain\myeeg.condition2.eph

+             .mrk Marker file
+         

+         

+             Contains the markers defined by the user.
+         

+         

+             There are 2 formats for .mrk file, the first being in binary
+             form (obsolete format), the second being in textual form, and
+             the one actually used as it can be easily read and modified by the user.

+             In any cases, the markers must be written ordered, sorted
+             first on their starting positions then on their ending positions (if
+             two markers have equal starting positions).

+             It is not advised to write duplicate markers with
+             exactly the same starting and ending positions. Cartool can read
+             them, can display them as superimposed markers, but you can expect
+             unpredictable results when it comes to computing (like averaging,
+             exporting, etc...). So don't.
+         

+         

+              
+         

+         

+             Text format:
+         

+         

+             A first line with this characters as a magic number:
+         
TL02

+             Then as many text lines as needed, structured this way:
+         
starting position     ending position    "description text in quote"

+             Note: the current limit for the description text is 31 chars.
+         

+         

+              
+         

+         

+             Binary format (obsolete):
+         

+         

+             A header followed by a list of markers, all in binary. The file
+             header structure is:
+         
struct mrkheader {
    char magic[4];                      // always 'TL01'
    } mrkheader;                        // size 4

+              
+         

+         

+             And the format for a single marker is:
+         
struct onemrk {
    long   Position;                    // from this TF
    long   To;                          // to this TF
    ushort Code;                        // trigger code
    ushort Type;                        // should always be 0x2 for a marker
    ushort Dummy;                       // not used, for the user
    char   Name[6];                     // name of the tag
    } onemrk;                           // size 20

+             .mtg Montage file
+         

+         

+             A text file that defines a montage to be used with the 
+                 EEG
+                 display
+              (it has to be created in any text editor, Cartool does
+             not provide an editor for this task).
+         

+         

+              
+         

+         

+             Format:
+         

+         

+             Always a first line with these characters as magic number:
+         
MT01

+             Then, each following lines can independently be any of these three formats:
+         
el
el1   el2
el1   el2   name

+             In the first case, the value of the electrode el
+             (the name of the electrode) is taken as is.

+             In the second case, the value is the result of subtracting el2
+             to el1.

+             The last case is the same as the second one, but a name is given to
+             override the default one (which would be  el1-el2).
+             This name must be written "as is", without quotes nor spaces.
+         

+         

+             Non-compliant lines (more fields, empty lines, unknown electrode
+             names..) are simply ignored.
+         

+         

+             You can put whatever you want in this file, repeating electrodes,
+             changing their order, including 
+                 auxiliaries
+                 or computed tracks
+             . The only limit is that the number of lines
+             should not be more than the number of electrodes in the original file.
+         

+         

+              
+         

+         

+             Example:
+         
MT01
1     2
2     3
3     4
4     5
Aux1  Aux2  DiffAux
10
9
8
7
6
5
4
3
2
1

+             .rois Regions Of Interest
+         

+         

+             This text file contains the required structural informations
+             to apply regions of interest calculus on data. At the moment, it
+             simply holds groups of indexes (of electrodes / solution points). You
+             may not be interested on the actual file format, but rather on how to 
+                 create
+                 the ROIs
+              in Cartool, or 
+                 how to make use
+                 of them
+             ?
+         

+         

+             First line, the magic number to indicate that the content is about
+             indexes (as opposite to voxels):
+         
RO01

+             Next 2 lines:
+         
Dimension_of_original_data
Number_of_rois

+             What is meant by  Dimension_of_original_data 
+             is simply the number of electrodes (or solution points) of  the
+             original data the rois were made from. This is used only for checking
+             you're not going to apply the .rois file to the wrong data, which
+             usually have different dimensions.
+         

+         

+             Then follows 2 lines for each roi:
+         
Roi_name
List_of_indexes

+             The name of the roi could be anything on the line, including spaces.
+             Quotes are not needed.
+         

+         

+             Within the list of indexes, use a space to separate between each
+             index. The end of line means the end of the list. Simple. And BTW, 
+                 indexes
+                 start from 1
+             , not 0.
+         

+         

+              
+         

+         

+             Example made from a setup of 125 electrodes, into 4 rois:
+         
RO01
125
4
Front Left
26 22 33 23 18 27 24 19 44 39 34 28 25 20 49 45 40 35 29 21 12 41 36 30 13 7 46 37 31
Front Right
14 8 15 9 1 10 3 2 4 124 123 122 121 120 5 119 118 117 116 113 112 111 110 115 114 107 106 105 109
Back Left
42 47 48 43 38 32 50 51 52 53 54 56 57 58 59 60 61 67 63 64 65 66 72 70 71 69 75 74
Back Right
81 88 104 80 87 94 99 103 79 86 93 98 102 78 92 97 101 77 85 91 96 108 84 100 83 90 89 95

+             .ris Results of Inverse Solution computation
+         

+         

+             This binary file is the final result of inverse solution
+             computations, after the matrix has been multiplied by the Eeg. It is
+             made of a header followed by a matrix of floats.
+         

+         

+              
+         

+         

+             Header structure
+         
struct risheader {
    char  magic[4];                      // always 'RI01'
    int32 numsolutionpoints;
    int32 numtimeframes;
    float samplingfrequency;             // in Herz
    char  isinversescalar;               // 1 if scalar, 0 if vectorial  (value, and not text)
    } risheader;                         // size 17

+              
+         

+         

+             Matrix structure
+         

+         

+             Number of rows:
+         
numrows = numtimeframes;

+             If the matrix contains scalar results, the number of columns is
+         
numcols = numsolutionpoints;

+             If the matrix contains vectorial results, a 3-uple (x,y,z) is
+             written, and the number of columns is
+         
numcols = 3 * numsolutionpoints;

+             The matrix is then written row by row:
+         
float matrix [ numrows ][ numcols ];

+              
+         

+         

+             Scalar example, for numrows rows:
+         
s0 s1 s2 ... snumcols-1
s0 s1 s2 ... snumcols-1
...
s0 s1 s2 ... snumcols-1

+             And vectorial example, for numrows rows:
+         
x0 y0 z0  x1 y1 z1 ... xnumcols-1 ynumcols-1 znumcols-1
x0 y0 z0  x1 y1 z1 ... xnumcols-1 ynumcols-1 znumcols-1
...
x0 y0 z0  x1 y1 z1 ... xnumcols-1 ynumcols-1 znumcols-1

+             .sef Simple Eeg Format
+         

+         

+             Simple (or safe, or stupid) binary format containing the
+             minimal data structure to describe correctly an EEG, either an
+             original recording or an ERP. It has a header, made of a fixed part
+             and a variable part, followed by the calibrated data (in micro-volts).
+         

+         

+              
+         

+         

+             Fixed part of the header:
+         
struct  TSefHeader
{
    int   Version;                       // magic number filled with the wide char 'SE01'
    int   NumElectrodes;                 // total number of electrodes
    int   NumAuxElectrodes;              //  out of which are auxiliaries
    int   NumTimeFrames;                 // time length
    float SamplingFrequency;             // frequency in Hertz
    short Year;                          // Date of the recording
    short Month;                         // (set to 00-00-0000 if unknown)
    short Day;
    short Hour;                          // Time of the recording
    short Minute;                        // (set to 00:00:00:0000 if unknown)
    short Second;
    short Millisecond;
};

+              
+         

+         

+             Variable part of the header:
+         

+         

+             The names of the channels, as a matrix of  NumElectrodes
+             x 8 chars.
+         
typedef char        TSefChannelName[8];  // 1 electrode name

+              
+         

+         

+             To allow an easy calculation of the data origin, be aware that names
+             are always stored on 8 bytes, even if the string length is
+             smaller than that. In this case, the remaining part is padded with
+             bytes set to 0, f.ex. two consecutive names:
+         

+         

+             binary
+             values           
+             70 112 122 00 00 00 00 00 65 70 55 00 00 00 00 00 ...
+         

+         

+             string equivalence      F  
+             P     z   
+             \0                     
+             A  F   7   \0
+         

+         

+              
+         

+         

+             Data part:
+         

+         

+             Starting at file position:
+         
sizeof ( TSefHeader ) + 8 * NumElectrodes

+             data are stored as a float (Little Endian convention - PC) matrix
+             written row by row:
+         
float data [ NumTimeFrames ][ NumElectrodes ];

+             .seg Segmentation
+         

+         

+             A text file used to store and display the results of the 
+                 segmentation
+                 process
+             .
+         

+         

+             First two lines is the header:
+         
number_of_clusters   number_of_files   number_of_time_frames
number_of_tracks   tracks_name1  tracks_name2  ...  tracks_namen

+             where
+         

+         

+             number_of_clusters    is the number of clusters from
+             the segmentation process

+             number_of_files       is the number of
+             files that have been segmented together

+             number_of_time_frames is the number of time frames of each segmented file

+             number_of_tracks      is the number of
+             informations saved for each file (f.ex. 5 for  Gfp Dis Seg GEV EV)

+             tracks_namei         
+             is the name of the ith track (f.ex. "Gfp")
+         

+         

+              
+         

+         

+             Then follow the data, one line per time frame (as in .eph
+             file). Each line concatenates the  number_of_tracks 
+             variables, one file after the other, f.ex.:
+         
File1Gfp  File1Dis  File1Seg  File1GEV  File2Gfp  File2Dis  File2Seg  File2GEV ... FilenGfp  FilenDis  FilenSeg  FilenGEV

+             .spi Solution Points Irregularly spaced
+         

+         

+             A text file consisting of a list of 3D points, used as
+             the solution points for the inverse solutions.
+             These points can be irregularly spaced, and don't need to be
+             on any sort of a grid.
+         

+         

+              

+             There is no header, and each line simply contains the 
+                 coordinates
+                 of one point
+              (floatting points values), and an optional name
+             (max 15 characters):
+         
x   y   z   optionalname

+             .spr Solution Points in Regular grid (obsolete)
+         

+         

+             Same format as .spi, but the points
+             have to be regularly spaced. That is, there has to be the same
+             distance (usually an integer value) between neighbors, and for all coordinates.
+         

+         

+             .tva Trigger VAlidation file
+         

+         

+             A text file that stores if a trigger was right or wrong, f.ex.
+             the choices a subject replied during an experiment.

+             There are two slightly different versions of this file, the
+             difference being rather semantic than on the format itself:

+              
+         

+         

+             Version 1
+         

+         

+             Is a file without header, containing a serie of lines which
+             have the following format:
+         
accepted   reaction_time   trigger_code

+             where:
+         

+         

+             accepted               
+             is either 0 (wrong answer / false) or 1 (correct
+             answer / true)

+             reaction_time  
+             is the reaction time of the answer, in milliseconds, 0 otherwise

+             trigger_code     
+             is the name of the trigger

+              
+         

+         

+             Version 2
+         

+         

+             Is a serie of lines identical to version 1, but the file starts 
+                 with
+                 the header
+             :
+         
TV01

+              
+         

+         

+             The difference between the two versions consist in which triggers are
+             being listed.
+         

+         

+             Version 1 is usually the ouput of the stimulation program,
+             all triggers of the experiment are therefore listed.
+             So if there are three triggers A, B, C repeated 100 times each, we
+             will have 300 lines in the file.
+         

+         

+             Version 2 is rather an output from Cartool itself,
+             usually from the averaging process. It
+             will list only the triggers that were considered during
+             the processing. If only triggers A and B were used, we will have only
+             200 + 1 lines in the file, the C trigger being ignored. These tva
+             files can be used to re-do the averaging.
+         

+         

+              
+         

+         

+             Example of version 1:
+         
1 1765  45
1 977.1 43
1 1191  36
0 0     56
0 0     35
1 1309  55
1 1696  49
1 1211  33
...

+             Example of version 2:
+         
TV01
1 0 On
1 0 Off
0 0 On
1 0 Off
1 0 On
0 0 Off
...

+             .vrb Verbose file
+         

+         

+             A text file generated during the 
+                 main
+                 processings
+              of Cartool. It records all the parameters set for
+             the processings and in some case the user's responses during the
+             procedure. These files are generated just for your convenience, to
+             help you store and recover how you computed that incredible files of yours!
+         

+         

+             .xyz Electrodes coordinates for head
+         

+         

+             A text file containing a list of electrodes coordinates on a
+             scalp. For more advanced electrodes setup (strips, clusters of
+             electrodes, grids...) see the .els format.
+         

+         

+             First line (though the radius of the cluster is not used anymore in Cartool):
+         
Number_of_electrodes  Radius_of_the_cluster

+             Then a list of coordinates, one per line:
+         
x   y   z   label

+             Example:
+         
   29    1
  9.510565E-0001 -3.090170E-0001 -0.000000E+0000 Fp2
  6.590572E-0001 -5.336940E-0001  5.299193E-0001 F4
  7.531501E-0020 -6.946584E-0001  7.193398E-0001 C4
 -6.590572E-0001 -5.336940E-0001  5.299193E-0001 P4
 -9.510565E-0001 -3.090170E-0001 -0.000000E+0000 O2
  5.877853E-0001 -8.090170E-0001 -0.000000E+0000 F8
  1.084202E-0019 -1.000000E+0000 -0.000000E+0000 T4
 -5.877853E-0001 -8.090170E-0001 -0.000000E+0000 T6
  8.619499E-0001 -4.019339E-0001  3.090170E-0001 AF4
  3.367557E-0001 -8.772786E-0001  3.420201E-0001 FC6
  3.535534E-0001 -3.535534E-0001  8.660254E-0001 FC2
 -3.535534E-0001 -3.535534E-0001  8.660254E-0001 CP2
 -3.367557E-0001 -8.772786E-0001  3.420201E-0001 CP6
  9.510565E-0001  3.090170E-0001 -0.000000E+0000 Fp1
  6.590572E-0001  5.336940E-0001  5.299193E-0001 F3
 -0.000000E+0000  6.946584E-0001  7.193398E-0001 C3
 -6.590572E-0001  5.336940E-0001  5.299193E-0001 P3
 -9.510565E-0001  3.090170E-0001 -0.000000E+0000 O1
  5.877853E-0001  8.090170E-0001 -0.000000E+0000 F7
 -0.000000E+0000  1.000000E+0000 -0.000000E+0000 T3
 -5.877853E-0001  8.090170E-0001 -0.000000E+0000 T5
  8.619499E-0001  4.019339E-0001  3.090170E-0001 AF3
  3.367557E-0001  8.772786E-0001  3.420201E-0001 FC5
  3.535534E-0001  3.535534E-0001  8.660254E-0001 FC1
 -3.535534E-0001  3.535534E-0001  8.660254E-0001 CP1
 -3.367557E-0001  8.772786E-0001  3.420201E-0001 CP5
  6.946584E-0001  0.000000E+0000  7.193398E-0001 Fz
  0               0               1              Cz
 -6.946584E-0001 -0.000000E+0000  7.193398E-0001 Pz

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+     

  
 
\ No newline at end of file
diff --git a/docs/ReferenceGuide/files-formats-others.html b/docs/ReferenceGuide/files-formats-others.html
index d91e3726..a2984ea8 100644
--- a/docs/ReferenceGuide/files-formats-others.html
+++ b/docs/ReferenceGuide/files-formats-others.html
@@ -2,908 +2,1132 @@
  
   Appendix D - Files Handled by Cartool
  
- 
-  

-   Appendix D

-   Files Handled by Cartool

-  

-    

-  

-   EEG files

-  
-  

-   Frequency files
Electrodes coordinates files

-   Solution Points files

-   Inverse Solution files
MRI files

-  

-   EEG files

-  

-   Raw EEG files

-  

-   

-    
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-    

-       

-        

-         Description

-       

-        

-         Version supported

-       

-        

-         Extension(s)

-       

-        

-         Creating

-       
-       

-        

-          

-       

-        

-         128

-       

-        

-         no

-       
-       

-        

-         CeeGraphIV

-         non-compressed data

-       

-        

-         eeg

-       

-        

-         no

-       
-       

-        

-         complete

-       

-        

-         bdf

-       

-        

-         no

-       
-       

-        

-         complete

-       

-        

-         eeg

-         dat

-       

-        

-         yes

-       
-       

-        

-         complete

-       

-        

-         sef

-       

-        

-         yes

-       
-       

-        

-         32 and 64 channels

-         (old versions only)

-       

-        

-         dsc + eeg + mrk

-       

-        

-         no

-       
-       

-        

-         complete

-       

-        

-         eeg

-       

-        

-         no

-       
    
-        
    
-         EaSys

-       

-        

-         EaSys2

-       

-        

-         d

-       

-        

-         no

-       
-       

-        

-         versions 1, 2, 3

-       

-        

-         nsr

-       

-        

-         no

-       
-       

-        

-         integer

-         float

-       

-        

-         raw

-         (gain + zero)

-       

-        

-         no

-       
-       

-        

-         complete

-       

-        

-         edf

-       

-        

-         yes

-       
-       

-        

-         partial

-       

-        

-         edf

-       

-        

-         no

-       
-       

-        

-         version 4

-       

-        

-         trc

-       

-        

-         no

-       
-       

-        

-         version 3, complete?

-       

-        

-         cnt

-       

-        

-         no

-       
-       

-        

-         ERPSS, complete?

-       

-        

-         rdf

-       

-        

-         no

-   

-  

-    

-  

-   ERP files

-  

-   

-    
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-    

-       

-        

-         Description

-       

-        

-         Version supported

-       

-        

-         Extension(s)

-       

-        

-         Creating

-       
-       

-        

-         complete

-       

-        

-         eph

-         ep

-       

-        

-         yes

-       
-       

-        

-         version 3, complete?

-       

-        

-         avg

-       

-        

-         no

-       
-       

-        

-         complete

-       

-        

-         eeg

-         dat

-       

-        

-         yes

-   

-  

-   Frequency files

-  

-   

-    
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-    

-       

-        

-         Description

-       

-        

-         Version supported

-       

-        

-         Extension(s)

-       

-        

-         Creating

-       
-       

-        

-         complete

-       

-        

-         freq

-       

-        

-         yes

-   

-  

-   Electrodes coordinates files

-  

-   

-    
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-    

-       

-        

-         Description

-       

-        

-         Version supported

-       

-        

-         Extension(s)

-       

-        

-         Creating

-       
    
-        
    
-         Cartool 
-         Electrodes Setup file, ELS

-       

-        

-         complete

-       

-        

-         els

-       

-        

-         yes

-       
    
-        
    
-         Cartool 
-         coordinates file, XYZ

-       

-        

-         complete

-       

-        

-         xyz

-       

-        

-         yes

-       
    
-        
    
-         Loreta 
-         coordinates file (identical to solution points, below)

-       

-        

-         complete

-       

-        

-         sxyz

-       

-        

-         no

-   

-  

-   Solution Points files

-  

-   

-    
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-    

-       

-        

-         Description

-       

-        

-         Version supported

-       

-        

-         Extension(s)

-       

-        

-         Creating

-       
-       

-        

-         complete

-       

-        

-         spi

-       

-        

-         yes

-       
    
-        
    
-         Loreta 
-         coordinates file

-       

-        

-         complete

-       

-        

-         sxyz

-       

-        

-         no

-       
    
-        
    
-         Besa coordinates file

-       

-        

-         complete

-       

-        

-         loc

-       

-        

-         no

-   

-  

-   Inverse Solution files

-  

-   

-    
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-    

-       

-        

-         Description

-       

-        

-         Version supported

-       

-        

-         Extension(s)

-       

-        

-         Creating

-       
-       

-        

-         complete

-       

-        

-         lf

-       

-        

-         yes

-       
    
-        
    
-         Cartool 
-         Inverse Solution Matrix

-       

-        

-         complete

-       

-        

-         is

-       

-        

-         yes

-       
    
-        
    
-         Cartool 
-         Results of Inverse Solution computation

-       

-        

-         complete

-       

-        

-         ris

-       

-        

-         yes

-       
    
-        
    
-         Loreta 
-         Inverse Solution Matrix

-       

-        

-         complete

-       

-        

-         spinv

-       

-        

-         no

-       
    
-        
    
-         Besa Lead Field Matrix

-       

-        

-         complete

-       

-        

-         lft

-       

-        

-         no

-   

-  

-   MRI files

-  

-   

-    
-     
-      
-      
-      
-      
-     
-        
-      
-      
-      
-      
-        
-     
-      
-      
-      
-      
-     
-        
-      
-      
-      
-      
-        
-		
-      
-      
-      
-      
-        
-    

-       

-        

-         Description

-       

-        

-         Version supported

-       

-        

-         Extension(s)

-       

-        

-         Creating

-       
-       

-        

-         Version 1 and 2

-       

-        

-         hdr + img
nii

-       

-        

-         yes

-       
-       

-        

-         3D volume,

-         little & big endian,

-         unsigned char /

-         unsigned short /

-         signed short /

-         signed short positive

-       

-        

-         hdr + img

-       

-        

-         yes

-       
-       

-        

-         Version 0 only

-       

-        

-         vmr

-       

-        

-         yes

-       
-       

-        

-         3D volume,

-         byte and short data types

-       

-        

-         fld

-       

-        

-         yes

-   

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    
+ 
+     

+         

+             Appendix D

+             Files Handled by Cartool
+         

+         

+              
+         

+         

+             EEG files
+         

+         
+         

+             Frequency files
Electrodes coordinates files

+             Solution Points files

+             Inverse Solution files
MRI files
+         

+         

+             EEG files
+         

+         

+             Raw EEG files
+         

+         

+             

+                 
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                 

+                             

+                                 

+                                     Description
+                         

+                             

+                                 

+                                     Version supported
+                         

+                             

+                                 

+                                     Extension(s)
+                         

+                             

+                                 

+                                     Creating
+                         

+                             
+                             

+                                 

+                                      
+                         

+                             

+                                 

+                                     128
+                         

+                             

+                                 

+                                     no
+                         

+                             
+                             

+                                 

+                                     CeeGraphIV

+                                     non-compressed data
+                         

+                             

+                                 

+                                     eeg
+                         

+                             

+                                 

+                                     no
+                         

+                             
+                             

+                                 

+                                     complete
+                         

+                             

+                                 

+                                     bdf
+                         

+                             

+                                 

+                                     no
+                         

+                             
+                             

+                                 

+                                     complete
+                         

+                             

+                                 

+                                     eeg

+                                     dat
+                         

+                             

+                                 

+                                     yes
+                         

+                             
+                             

+                                 

+                                     complete
+                         

+                             

+                                 

+                                     sef
+                         

+                             

+                                 

+                                     yes
+                         

+                             
+                             

+                                 

+                                     32 and 64 channels

+                                     (old versions only)
+                         

+                             

+                                 

+                                     dsc + eeg + mrk
+                         

+                             

+                                 

+                                     no
+                         

+                             
+                             

+                                 

+                                     complete
+                         

+                             

+                                 

+                                     eeg
+                         

+                             

+                                 

+                                     no
+                         

+                             
    
+                                 
    
+                                     EaSys
+                         

+                             

+                                 

+                                     EaSys2
+                         

+                             

+                                 

+                                     d
+                         

+                             

+                                 

+                                     no
+                         

+                             
+                             

+                                 

+                                     versions 1, 2, 3
+                         

+                             

+                                 

+                                     nsr
+                         

+                             

+                                 

+                                     no
+                         

+                             
+                             

+                                 

+                                     integer

+                                     float
+                         

+                             

+                                 

+                                     raw

+                                     (gain + zero)
+                         

+                             

+                                 

+                                     no
+                         

+                             
+                             

+                                 

+                                     complete
+                         

+                             

+                                 

+                                     edf
+                         

+                             

+                                 

+                                     yes
+                         

+                             
+                             

+                                 

+                                     partial
+                         

+                             

+                                 

+                                     edf
+                         

+                             

+                                 

+                                     no
+                         

+                             
+                             

+                                 

+                                     version 4
+                         

+                             

+                                 

+                                     trc
+                         

+                             

+                                 

+                                     no
+                         

+                             
+                             

+                                 

+                                     version 3, complete?
+                         

+                             

+                                 

+                                     cnt
+                         

+                             

+                                 

+                                     no
+                         

+                             
+                             

+                                 

+                                     ERPSS, complete?
+                         

+                             

+                                 

+                                     rdf
+                         

+                             

+                                 

+                                     no
+                         

+             

+         

+         

+              
+         

+         

+             ERP files
+         

+         

+             

+                 
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                 

+                             

+                                 

+                                     Description
+                         

+                             

+                                 

+                                     Version supported
+                         

+                             

+                                 

+                                     Extension(s)
+                         

+                             

+                                 

+                                     Creating
+                         

+                             
+                             

+                                 

+                                     complete
+                         

+                             

+                                 

+                                     eph

+                                     ep
+                         

+                             

+                                 

+                                     yes
+                         

+                             
+                             

+                                 

+                                     version 3, complete?
+                         

+                             

+                                 

+                                     avg
+                         

+                             

+                                 

+                                     no
+                         

+                             
+                             

+                                 

+                                     complete
+                         

+                             

+                                 

+                                     eeg

+                                     dat
+                         

+                             

+                                 

+                                     yes
+                         

+             

+         

+         

+             Frequency files
+         

+         

+             

+                 
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                 

+                             

+                                 

+                                     Description
+                         

+                             

+                                 

+                                     Version supported
+                         

+                             

+                                 

+                                     Extension(s)
+                         

+                             

+                                 

+                                     Creating
+                         

+                             
+                             

+                                 

+                                     complete
+                         

+                             

+                                 

+                                     freq
+                         

+                             

+                                 

+                                     yes
+                         

+             

+         

+         

+             Electrodes coordinates files
+         

+         

+             

+                 
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                 

+                             

+                                 

+                                     Description
+                         

+                             

+                                 

+                                     Version supported
+                         

+                             

+                                 

+                                     Extension(s)
+                         

+                             

+                                 

+                                     Creating
+                         

+                             
    
+                                 
    
+                                     Cartool
+                                     Electrodes Setup file, ELS
+                         

+                             

+                                 

+                                     complete
+                         

+                             

+                                 

+                                     els
+                         

+                             

+                                 

+                                     yes
+                         

+                             
    
+                                 
    
+                                     Cartool
+                                     coordinates file, XYZ
+                         

+                             

+                                 

+                                     complete
+                         

+                             

+                                 

+                                     xyz
+                         

+                             

+                                 

+                                     yes
+                         

+                             
    
+                                 
    
+                                     Loreta
+                                     coordinates file (identical to solution points, below)
+                         

+                             

+                                 

+                                     complete
+                         

+                             

+                                 

+                                     sxyz
+                         

+                             

+                                 

+                                     no
+                         

+             

+         

+         

+             Solution Points files
+         

+         

+             

+                 
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                 

+                             

+                                 

+                                     Description
+                         

+                             

+                                 

+                                     Version supported
+                         

+                             

+                                 

+                                     Extension(s)
+                         

+                             

+                                 

+                                     Creating
+                         

+                             
+                             

+                                 

+                                     complete
+                         

+                             

+                                 

+                                     spi
+                         

+                             

+                                 

+                                     yes
+                         

+                             
    
+                                 
    
+                                     Loreta
+                                     coordinates file
+                         

+                             

+                                 

+                                     complete
+                         

+                             

+                                 

+                                     sxyz
+                         

+                             

+                                 

+                                     no
+                         

+                             
    
+                                 
    
+                                     Besa coordinates file
+                         

+                             

+                                 

+                                     complete
+                         

+                             

+                                 

+                                     loc
+                         

+                             

+                                 

+                                     no
+                         

+             

+         

+         

+             Inverse Solution files
+         

+         

+             

+                 
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                 

+                             

+                                 

+                                     Description
+                         

+                             

+                                 

+                                     Version supported
+                         

+                             

+                                 

+                                     Extension(s)
+                         

+                             

+                                 

+                                     Creating
+                         

+                             
    
+                                 
    
+                                     Cartool
+                                     Lead Field Matrix
+                         

+                             

+                                 

+                                     complete
+                         

+                             

+                                 

+                                     lf
+                         

+                             

+                                 

+                                     yes
+                         

+                             
    
+                                 
    
+                                     Cartool
+                                     Inverse Solution Matrix
+                         

+                             

+                                 

+                                     complete
+                         

+                             

+                                 

+                                     is
+                         

+                             

+                                 

+                                     yes
+                         

+                             
    
+                                 
    
+                                     Cartool
+                                     Results of Inverse Solution computation
+                         

+                             

+                                 

+                                     complete
+                         

+                             

+                                 

+                                     ris
+                         

+                             

+                                 

+                                     yes
+                         

+                             
    
+                                 
    
+                                     Loreta
+                                     Inverse Solution Matrix
+                         

+                             

+                                 

+                                     complete
+                         

+                             

+                                 

+                                     spinv
+                         

+                             

+                                 

+                                     no
+                         

+                             
    
+                                 
    
+                                     Besa Lead Field Matrix
+                         

+                             

+                                 

+                                     complete
+                         

+                             

+                                 

+                                     lft
+                         

+                             

+                                 

+                                     no
+                         

+             

+         

+         

+             MRI files
+         

+         

+             

+                 
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                 

+                             

+                                 

+                                     Description
+                         

+                             

+                                 

+                                     Version supported
+                         

+                             

+                                 

+                                     Extension(s)
+                         

+                             

+                                 

+                                     Creating
+                         

+                             
+                             

+                                 

+                                     Version 1 and 2
+                         

+                             

+                                 

+                                     hdr + img
nii
+                         

+                             

+                                 

+                                     yes
+                         

+                             
+                             

+                                 

+                                     3D volume,

+                                     little & big endian,

+                                     unsigned char /

+                                     unsigned short /

+                                     signed short /

+                                     signed short positive
+                         

+                             

+                                 

+                                     hdr + img
+                         

+                             

+                                 

+                                     yes
+                         

+                             
+                             

+                                 

+                                     Version 0 only
+                         

+                             

+                                 

+                                     vmr
+                         

+                             

+                                 

+                                     yes
+                         

+                             
+                             

+                                 

+                                     3D volume,

+                                     byte and short data types
+                         

+                             

+                                 

+                                     fld
+                         

+                             

+                                 

+                                     yes
+                         

+             

+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+     

  
 
\ No newline at end of file
diff --git a/docs/ReferenceGuide/frequency-analysis.html b/docs/ReferenceGuide/frequency-analysis.html
index 96c5cbbb..0209d555 100644
--- a/docs/ReferenceGuide/frequency-analysis.html
+++ b/docs/ReferenceGuide/frequency-analysis.html
@@ -2,1055 +2,1382 @@
  
   Frequency Analysis
  
- 
-  

-   Frequency Analysis

-  

-    

-  

-   What kind of analysis?
How to run the frequency analysis

-   Results
FFT Approximation
Display: Frequency Display  
-   and   Displaying 
-   maps for frequenciess

-  

-   Technical points

-  
-  

-   What kind of analysis?

-  

-   Currently, the analysis available are:

-  
-  

-   However, new analysis will be added in the future. Also, you won't 
-   find here the theory behind these methods, you can browse the 
-   internet about
-    the FFT, and the
-    S-Transform.

-  

-   You have to first run the analysis, which generates new files,
-    and then open those files to see the results. This part only refers 
-   to the analysis itself, the other part is how
-    to work with the display.

-   

-   

-   

-   

-  

-   * see article  Intracerebral dipole 
-   source localization for FFT power maps  by D. Lehman and 
-   C.M. Michel, in Electroencephalography and clinical Neurophysiology,
-    1990, Elsevier.

-  

-   How to run the frequency analysis

-  

-   Call the dialog from Tools
-    | Frequency Analysis menu, which is context sensitive:

-  
    
-   
  • 
-   
    
-    Called from an EEG file, the analysis 
-    will apply only to this very current file.
    
-   
  • 
-   
    
-    In any other case, the dialog will 
-    operate in Batch mode, requiring you to later select some files.
    
-   

-  

-    

-  

-   The following dialog pops out. Fill the parameters which are relevant 
-   for you, then click either on Process Current or Batch Process 
-   (according to how the dialog was invoked):

-  

-   

-    

-   

-  

-   
-       
-     
-     
-       
-	   
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-       
-     
-     
-       
-	   
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-       
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-       
-     
-     
-       
-    
-     
-     
-    
-       
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-   

-      

-       Presets:

-      

-       The most used sets of parameters, which make use of either FFT's or 
-       of S-Transform.

-      

-       Presets can be found either for surface or intra-cranial recordings,
-        for the Power Maps and FFT Approximation, and for all 
-       these cases, with variations using a STFT (more time 
-       resolution). There are also presets for the Wavelet S-Transform.

-      

-        

-      

-       The most important parameters will be set, still some 
-       parameters have to be set manually! And, as usual, double 
-       check that all your settings make sense...

-      

-       Tracks to Analyse

-      

-        

-      

-       Tracks to analyse

-      

-       From an opened EEG:

-       Prefilled with the current selected 
-       tracks, otherwise with the current displayed tracks.

-      

-       In Batch Mode:

-       On first call, default is *, meaning all regular
-        tracks.

-      

-       You can of course modify this list. See
-        important note about notation.

-      

-       Names from XYZ:

-      

-       Optionally pointing to a file with the electrodes coordinates and 
-       names (such as .els and .xyz).
-        The names of the electrodes are taken from this file, 
-       overriding the original names from the EEG (i.e. you can rename the electrodes).

-       Be careful that the list above respect these names, otherwise you 
-       will get an error message.

-      

-       Constraints as in the link
-        mechanism must be respected, such as same number of electrodes, 
-       same order, etc...

-      

-       Time Windows

-      

-        

-      

-       Analyse From [TF]:

-      

-       First time frame to be analysed,

-      

-       to

-      

-       and last time frame required for analysis.

-      

-       (...  after clipping)

-      

-       For info, the last time frame to be actually analysed, with 
-       current parameters.

-      

-       This number might slightly differ from the previous field due to the 
-	   subdivision in time windows.

-      

-       End of File

-      

-       Automatically set the last time frame to the actual end of the 
-       current file. Useful in Batch Mode,
-        if the files have different lengths.

-      

-       Windows Size:

-      

-       For an FFT analysis, data is analyzed by blocks, aka 
-	   time windows:

-	  
    
-		  
  • Time windows are asually integer multiples of the 
-		  sampling frequency, like 2x or 1x.
    • 
-		  
  • The bigger the time window, the higher the frequency precision, 
-		  but the lower the time resolution
    • 
-		  
  • The smaller the time window, the lower the frequency precision, 
-		  and the higher the time resolution
    • 
-	  

-	  

-       

-	  

-       For the S-Transform, there is only one single big window which 
-	   is the full time range to be analyzed.

-	  

-       See this note about time frequency issues.

-      

-       Windows Step:

-      

-       How much stepping to do when fetching the next time window:

-      
    
-       
  • 
-       
    
-        1 TF: one time frame, the shortest step,
    
-       
  • 
-       
    
-        25% Window: 25% of the window size is used, which means 25% of 
-        new data incorporated,
    
-       
  • 
-       
    
-        100% Window: step across the whole current window, without any overlap.
    
-       

-      

-        

-      

-       Note that a 1 TF step is equivalent to perform a Short
-        Term Fourier Transform (STFT).

-      

-       A 25% step (BTW used to be 75% overlap) is a safe way to add 
-       significantly new data to the time window.

-      

-       A 100% step is useful in case you have epochs pasted into a single 
-       file, and you shouldn't mix their data. So setting the window size to 
-       the epoch length, and stepping 100% is the way to go.

-      

-       windows step ... [ms]

-      

-       Showing the resulting step in [ms] between successive time windows.

-      

-       Number of Window(s):

-      

-       Showing the number of time windows you get with the current parameters.

-      

-       If the S-Transform analysis is used, there is only 1 window which 
-       extends exactly on the time range selected above.

-      

-       Frequencies

-      

-        

-      

-       Sampling Frequency:

-      

-       The current sampling frequency, if available from the current file.

-      

-       If in Batch mode, however, this field can and should be filled by hand.

-      

-       Frequency Range and Resolution:

-      

-       The range of frequencies and the frequency step/resolution 
-       you can obtain with your current parameters (Sampling Frequency and 
-       Window Size).

-      

-       For example, if step is 0.5 Hz, 
-       frequencies actually available will be: 0, 0.5, 1, 1.5 etc... Hz.

-      

-       Saving Frequency Interval:

-      

-       Specify a single interval of frequencies to be saved in 
-       the output file. Give the lowest and the highest frequencies of the 
-       interval, plus a step/resolution.

-      

-       The saved frequency steps can be bigger than the minimum available, 
-       f.ex. you can save by steps of 1 Hz even if the analysis offers you a 
-       0.5 Hz resolution. In this case Cartool will average
-        neighboring frequencies, therefore increasing the signal to 
-       noise ratio.

-      

-        

-      

-       Remember that it is always a good idea to constrain the saved frequency 
-       range to be as small as possible according to your data. Otherwise 
-	   you will have bigger and slower files, and for no use.

-      

-       Log Frequencies:

-      

-       Frequencies are inherently logarithmic by nature. For small ranges of 
-	   frequencies, or to comply with usages, the whole interval of frequencies 
-	   is often used. But for more accurate, or for broader ranges of 
-	   frequencies, it is highly recommended to use a logarithmic scale instead.

-      	 

-      

-       split into XX per Decade

-      

-       This tells how many subdivisions to save per decades (frequencies 
-	   multipled by 10).

-	  

-       F.ex. 20 values per decade means:

-	  
    
-		  
  • 20 frequency values for interval 1 to 10 [Hz]
    • 
-		  
  • 20 frequency values for interval 10 to 100 [Hz]
    • 
-		  
  • etc..
    • 
-	  

-		   

-      

-       Saving Frequency Bands:

-      

-       Save any number of bands, computing the average for each 
-       of them.

-      

-       Give the list of bands, separated either by a space, a comma or 
-       semi-colon. Be careful to actually order the bands: Cartool 
-       will follow the exact sequence you specify, so keep things consistant by 
-	   using increasing frequency bands!

-      

-       F.ex.:  0-4, 4-8, 8-12, 12-20

-      

-       See this note about averaging frequencies.

-      

-       Type of Analysis

-      

-       You can choose between 3 well proven and robust analysis:
    
-		  
  • FFT
    • 
-		  
  • FFT Approximation
    • 
-		  
  • Wavelet (S-Transform)
    • 
-	  

-		

-      

-       

-        FFT

-      

-       The classical FFT, or the STFT (Short Term Fourier 
-       Transform) if the Windows Step parameter is set to 1 TF.

-      

-       With Average Reference data and saving the Square Norm, you can 
-       compute the Power Maps on surface recordings (see the Presets).

-      

-       

-        FFT Approximation

-      

-       Projection on the least-square deviation line going through the FFT 
-       for each window (of the average-referenced data), aka best dipole 
-       fitting. Results are in the "real" values, and will look 
-       like an EEG with polarity (see the Presets).

-      

-       See this note about averaging FFT approximation.

-      

-       

-        S-Transform

-      

-       The Stockwell Transform allows for some optimal time and frequency resolution.

-      

-       Note that it applies only to a single window, which can be as big as 
-       needed by your analysis. However to reduce the computational cost, 
-       and for big ranges, use rather the plain FFT and keep the S-Transform 
-       for shorter time ranges (like a magnifier on a given area).

-      

-       FFT Windowing Function:

-      

-        

-      

-       None

-      

-       No windowing function added (or, to be totally precise, using a Flat Top 
-       windowing function).

-      

-       Hanning

-      

-       Hanning windowing function. Try this 
-       to learn more. Also see this technical point.

-       Recommended most of the time, except if you have no overlap between 
-	   windows, or a a single time window.

-      

-       Time Windows are:

-      

-        

-      

-       Averaged

-      

-       Analysed windows are averaged, hence the result will be a single 
-       "Time Point". See this note 
-       about the averaging.

-      

-       in Sequence

-      

-       Analysed windows are written sequentially, so you can have an idea of 
-       the frequencies in time. See this note 
-       about the time reference.

-      

-       FFT Time Windows Rescaling:

-      

-       The FFT formula includes specifies a normalization, or divisive factor. 
-	   Problem is there is no agreement on which formula to use in practice. 
-	   Here you can specify the one to your liking:
    
-		  
  • None: no rescaling at all
    • 
-		  
  • Square Root of Time Window size
    • 
-		  
  • Time Window size, aka Parseval formula.
    
-		  This is the most correct one, so if you don't know any better, keep 
-		  this option!
    • 
-	  

-	  

-       

-       Note: this option is relevant only for single forward FFT's, 
-	   and not for the S-Transform (which is a forward + backward FFT all in 
-	   one!)

-      

-       Outputting Values:

-      

-       Results of the analysis are always complex values. Usage is to 
-	   save only the norm or power of these complex values, but you can still 
-	   control what to actually save according to your needs:
    
-		  
  • Real part
    Only the real part of the complex 
-		  value. Only available for the FFT Approximation analysis, though.
    • 
-		  
  • Norm
    The norm, or intensity of the results.
    • 
-		  
  • Power (Squared Norm)
    The square of the norm, 
-		  or the power of the results. Quite the default.
    • 
-		  
  • Complex
    The complete complex values, written 
-		  following the C style (double real + double imag).
    • 
-		  
  • Phase
    The phase of the values, in the [0 .. 
-		  2Pi) range
    • 
-	  

-		

-      

-       Reference of Data

-      

-        

-      

-       No Reference

-      

-       Use the same reference as when the file(s) was(were) written, that 
-       is, no change in reference.

-      

-       Use Current Reference

-      

-       Use the reference currently in use. Useful only if the files have 
-       already been opened in Cartool, and the user has changed the reference.

-      

-       Average Reference

-      

-       Use the average reference, 
-       overriding current reference.

-      

-       Other Reference

-      

-       Use the average of the specified list of electrodes. If only 
-       one electrode is specified, this will be the reference.

-      

-       Options

-      

-        

-      

-       Optional filename infix override:

-      

-       The saved filenames will have the specified characters inserted. 
-       Default is a combination of the type of analysis and frequency range, 
-       which can be long and clumsy for your use.

-      

-       All Results in Single freq File

-      

-       This is the default ouput, a binary file 
-       holding all the results (frequencies, electrodes, and all time windows).

-      

-       Use this to save space on your disk, and / or to later use the Frequency
-        Display of Cartool.

-      

-       All Results in a Sub-Directory

-      

-       Optionally saving all results in a sub-directory for a better 
-	   organization. Kind of hand if you wish to split the data with the 
-	   splitting options below.

-      

-       Open File(s) Upon Completion

-      

-       ...of the analysis. Just be careful in Batch
-        Mode, this could open a lot of files! (the original EEG files 
-       are opened one at a time, then closed when done).

-      

-       Splitting Results:

-      

-       Frequency analysis results are 3D data by nature: electrodes x time x 
-	   frequencies. To facilate either the display, the export or the processing 
-	   with other toolboxes, it comes in handy to split these data into 
-	   smalller, 2D files.

-	  

-       

-	  

-       Note: You can always break 
-	   down .freq files, or merge 2D files back into
-	   .freq files later on.

-		   

-      

-       

-        By Electrode

-      

-       Splitting results with one file per electrode.

-      	 

-      

-       

-        By Frequency

-      

-       Splitting results with one file per frequency.

-		

-      

-       

-        By Spectrum

-      

-       Splitting results with one file per spectrum.

-	  

-       If you process sequentially 
-       the different time windows, there will be as many output files 
-       as there are of these time windows.

-      

-       If you average the time 
-       windows, a single file with the average spectrum is produced.

-      

-       Shrinking file size by.. Downsampling to Highest Freq.

-      

-       Especially useful for the S-Transform, the resulting files might very big 
-	   and carrying way too much temporal information. F.ex. if the analyzed 
-	   frequencies were in the range [5..50], you don't really care for time 
-	   steps smaller than 20 [ms]. This option will optimally downsample the 
-	   time resolution according to your parameters.

-       Don't use it however if you wish to preserve a per time frame 
-	   correspondance with your original data, though.

-      

-       Process Current

-      

-       Enabled when called from an EEG. The analysis applies only to this 
-       current file.

-      

-       This button remains disabled until all the parameter 
-       dialogs have received enough (and consistent) informations. If 
-       this is not the case, first check the current dialog: if its 
-       "Next" button is disabled, the problem is in the current 
-       dialog. Otherwise, browse the other dialogs for some missing informations.

-      

-       Batch Process

-      

-       Enabled when not called from an EEG. This will open a dialog for you 
-       to pick the set of files (even from different directories) to 
-       be analysed.

-      

-       This button remains disabled until all the parameter 
-       dialogs have received enough (and consistent) informations. If 
-       this is not the case, first check the current dialog: if its 
-       "Next" button is disabled, the problem is in the current 
-       dialog. Otherwise, browse the other dialogs for some missing informations.

-      

-       You can Drag & Drop files directly to run the Batch Process!

-      

-       Cancel

-      

-       Quit the dialog.

-      

-       Help

-      

-       Launch the Help to the right page (should be here...).

-  

-   Frequency analysis - Results

-  
    
-   
  • 
-   
    
-    .freq file with 
-    all the important informations, if this option 
-    has been selected (of course recommended!). Freq files are written in 
-    the same directories as their sources. Open 
-    them to work with the results.
    
-   
  • 
-   
    
-    .sef files for each 
-    split electrode, frequency or spectrum, if any of splitting options have 
-	been used.
    
-   
  • 
-   
    
-    .ApproxEeg.ep 
-    file(s), for the approximated EEG of each electrode, for each saved 
-    time window (if the "Spectrum" option above has been 
-    selected). Note that these files also have the frequencies on the 
-    horizontal axis, like the Spectrum.
    
-   
  • 
-   
    
-    Verbose file ...<type of analysis>.vrb 
-     (text), showing all the parameters.
    
-   

-  

-   FFT Approximation

-  

-   The FFT Approximation is a very convenient way 
-   to retrieve an EEG-like signal, made of signed values, from 
-   the FFT results.

-  

-   To begin with, the FFT, when applied to a time window, always returns 
-   results in the Complex space C. Each electrode, for each 
-   frequency, is a complex number made of two parts, the real and 
-   imaginary values. Hence, we can plot them on a plane (X is the real 
-   axis, Y is the imaginary axis), here for one time window, and three 
-   successive frequencies:

-  

-   

-  

-    

-  

-   The FFT Approximation finds the best fitting line in the 
-   average referenced data (equivalent to the best fitting dipole), then projects 
-   the electrodes complex values on this axis. Being left with a single 
-   dimension, a line, we arbitrarily assign a polarity to one direction, 
-   and voilà, we have real,
-    signed, scalar values. See again the same three frequencies, for 
-   one time window, with the resulting projected electrodes:

-  

-   

-  

-    

-  

-   We repeat this operation for each time window, see here the first three
-    time windows, for a single frequency (see the rotating pattern 
-   due to phase shift of the signal):

-  

-   

-  

-    

-  

-   You may have noted that the final polarity is arbitrary, which should 
-   be accounted for in case of averaging.
-    As long as patterns / topographies are concerns, this is not a real 
-   problem, though.

-  

-   Frequency analysis - Technical points

-  

-   Files that can be processed

-  

-   Input files can be anything that looks like tracks:

-  
-  

-   Reference of data

-  

-   Be aware that changing the reference of the data greatly 
-   affects the shape of the signal, and therefor its frequencies. 
-   This is why the Power Maps and FFT Approximation 
-   presets activate the average reference (as well as some other 
-   parameters), to prevent any accidental change.

-   By the way, don't use these two methods for intra-cranial electrodes, 
-   this does not make sense at all (again, see article)!

-  

-   Time reference for each window

-  

-   Each window is a part cut from the original file, say from  t 
-    to  t + window_size - 1. Once processed, the results are frequencies
-    for that whole window. Therefor, it is natural to attribute the mean
-    time  t + window_size / 2  of that window as 
-   its time position in the output file.

-  

-   Averaging windows

-  

-   Average occurs at the very last stage of the processing. For example, after 
-   the Power Maps have been computed. This is not equivalent to 
-   the Power Maps of the mean FFT.

-  

-   Windowing function

-  

-   When using the Hanning windowing function, the results after analysis 
-   are multiplied by a factor 2 to account for the fading 
-   introduced by the method.

-  

-   Time / frequency resolution issue

-  

-   Smaller time windows gives a higher time resolution, 
-   but a lower frequency resolution. Conversely, bigger time 
-   windows gives a lower time resolution, and a higher frequency 
-   resolution. The dialog, by default, suggest a compromise between the 
-   time and frequency resolution, which the user can change.

-  

-   Here you can see the same time range analysed with a small (64), a 
-   medium (256) and a large (1024) time window (for a sampling frequency 
-   of 256 Hz):

-  

-   

-   

-   

-  

-   Averaging frequencies together

-  

-   Frequencies saved and computed 
-   usually differ, in the sense that often, more frequencies are 
-   available from the transformation than there will be written to file.
-    The most obvious case is when saving a frequency band, all 
-   frequencies within that band will be averaged together into a single 
-   result. Though, it also applies to the interval case, f.ex. if the 
-   saved frequencies are stepping by 1 Hz, and the transformation allows 
-   finer steps of 0.5 Hz.

-  

-   To take benefit from that situation, Cartool will average as much 
-   as it can from the available frequencies to produce the requested 
-   output results. Let's see how this works.

-  

-   In the frequency band case:

-  
    
-   
  • 
-   
    
-    All frequencies within the specified range (including both limits), 
-    with all the available steps (say, again, 0.5 Hz) will be averaged together.
    
-    
  • But if the available steps are smaller than 0.25 
-    Hz, f.ex. 0.125 Hz, the steps taken will be limited to those 
-    multiples of 0.25 Hz. Stated otherwise, Cartool averages up to 0.25 
-    Hz steps.
    
-    
  • In the S-Transform case, the number of 
-    frequencies averaged together has been limited to a total of 25 per 
-    band. Because the S-Transform is very smooth, and it does not provide 
-    much informations to average more, and because this transformation is 
-    very costly!
    
-   

-  

-   F.ex.: band 3-8 Hz, with steps of 0.5 Hz, will average frequencies 3, 
-   3.5, 4, 4.5, 5, 5.5, 6, 6.5, 7, 7.5 and 8 Hz.

-  

-    

-  

-   In the interval case:

-  
    
-   
  • 
-   
    
-    You have to specify a range of frequencies, plus a step to save. If 
-    your step is greater than the transformation available step, an 
-    averaging will occur. F.ex. you ask from 3 to 8 Hz, by steps of 1 Hz, 
-    but the resolution allows up to 0.25 Hz, then frequencies 3, 3.25, 
-    3.5 and 3.75 are averaged together for your first saved frequency. 
-    Then 4, 4.25, 4.5 and 4.75 for your second saved frequency etc... 
-    Stated otherwise, they are treated like a serie of small bands.
    
-    
  • As for the band case, averaged steps will be 
-    limited to a minimum of 0.25 Hz.
    
-    
  • As for the band case, the number of 
-    frequencies averaged together for the S-Transform for each step is 
-    also limited to 25 (but this is quite unlikely to happen!).
    
-   

-  

-    

-  

-   In any case, you can see in the verbose file what are exactly
-    the frequencies that have been averaged together, if you have 
-   any doubt.

-  

-   FFT Approximation and averaging

-  

-   FFT Approximation results can also be averaged, as explained
-    here. However some more checkings are to be done.

-  

-   The problems arise from the fact that the results are signed, real values,
-    as an actual EEG would look like. However, during the FFT 
-   Approximation process, the polarity of each map 
-   has been assigned to an arbitrary value: a map can be either m 
-   or -m, we can not know. This is an important issue when 
-   averaging together these maps, as to avoid them to cancel each other 
-   for this sign reason.

-  

-   Thus, Cartool, when dealing with averaging FFT Approximation maps, 
-   will perform sign inversions of the maps whose correlation with 
-   each others are negative. After the sign inversion the regular 
-   summation can take place.

-  

-   Averaging is done after conversion

-  

-   When averaging many frequencies together (either this
-    case or this case), the averaging 
-   takes place after converting the results from complex to real 
-   values, usually by taking the norm, the squared norm of the results, 
-   or through the FFT Approximation.

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    
+ 
+     

+         

+             Frequency Analysis
+         

+         

+              
+         

+         

+             What kind of analysis?
How to run the frequency analysis

+             Results
FFT Approximation
Display: Frequency Display 
+             and   
+                 Displaying
+                 maps for frequenciess
+             
+         

+         

+             Technical points
+         

+         
+         

+             What kind of analysis?
+         

+         

+             Currently, the analysis available are:
+         

+         
+         

+             However, new analysis will be added in the future. Also, you won't
+             find here the theory behind these methods, you can browse the
+             internet 
+                 about
+                 the FFT
+             , and 
+                 the
+                 S-Transform
+             .
+         

+         

+             You have to first run the analysis, which generates new files,
+             and then open those files to see the results. This part only refers
+             to the analysis itself, the other part is 
+                 how
+                 to work with the display
+             .

+             

+             

+             

+         

+         

+             * see article  
+                 Intracerebral dipole
+                 source localization for FFT power maps
+               by D. Lehman and
+             C.M. Michel, in Electroencephalography and clinical Neurophysiology,
+             1990, Elsevier.
+         

+         

+             How to run the frequency analysis
+         

+         

+             Call the dialog from 
+                 
+                     Tools
+                     | Frequency Analysis
+                 
+              menu, which is context sensitive:
+         

+         
    
+             
  • 
+                 
    
+                     Called from an EEG file, the analysis
+                     will apply only to this very current file.
+                 
    
+             
  • 
+                 
    
+                     In any other case, the dialog will
+                     operate in Batch mode, requiring you to later select some files.
+                 
    
+         

+         

+              
+         

+         

+             The following dialog pops out. Fill the parameters which are relevant
+             for you, then click either on Process Current or Batch Process
+             (according to how the dialog was invoked):
+         

+         

+             

+                 
+             

+         

+         

+             
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+             

+                         

+                             Presets:
+                     

+                         

+                             The most used sets of parameters, which make use of either FFT's or
+                             of S-Transform.
+                         

+                         

+                             Presets can be found either for surface or intra-cranial recordings,
+                             for the Power Maps and FFT Approximation, and for all
+                             these cases, with variations using a STFT (more time
+                             resolution). There are also presets for the Wavelet S-Transform.
+                         

+                         

+                              
+                         

+                         

+                             The most important parameters will be set, still 
+                                 
+                                     some
+                                     parameters have to be set manually!
+                                 
+                              And, as usual, double
+                             check that all your settings make sense...
+                     

+                         

+                             Tracks to Analyse
+                     

+                         

+                              
+                     

+                         

+                             Tracks to analyse
+                     

+                         

+                             From an opened EEG:

+                             Prefilled with the current selected
+                             tracks, otherwise with the current displayed tracks.
+                         

+                         

+                             In Batch Mode:

+                             On first call, default is *, meaning all 
+                                 regular
+                                 tracks
+                             .
+                         

+                         

+                             You can of course modify this list. 
+                                 See
+                                 important note about notation
+                             .
+                     

+                         

+                             Names from XYZ:
+                     

+                         

+                             Optionally pointing to a file with the electrodes coordinates and
+                             names (such as .els and .xyz).
+                             The names of the electrodes are taken from this file,
+                             overriding the original names from the EEG (i.e. you can rename the electrodes).

+                             Be careful that the list above respect these names, otherwise you
+                             will get an error message.
+                         

+                         

+                             Constraints as in the 
+                                 link
+                                 mechanism
+                              must be respected, such as same number of electrodes,
+                             same order, etc...
+                     

+                         

+                             Time Windows
+                     

+                         

+                              
+                     

+                         

+                             Analyse From [TF]:
+                     

+                         

+                             First time frame to be analysed,
+                     

+                         

+                             to
+                     

+                         

+                             and last time frame required for analysis.
+                     

+                         

+                             (...  after clipping)
+                     

+                         

+                             For info, the last time frame to be actually analysed, with
+                             current parameters.
+                         

+                         

+                             This number might slightly differ from the previous field due to the
+                             subdivision in time windows.
+                     

+                         

+                             End of File
+                     

+                         

+                             Automatically set the last time frame to the 
+                                 actual end of the
+                                 current file
+                             . Useful in Batch Mode,
+                             if the files have different lengths.
+                     

+                         

+                             Windows Size:
+                     

+                         

+                             For an FFT analysis, data is analyzed by blocks, aka
+                             time windows:
+                         

+                         
    
+                             
  • 
+                                 Time windows are asually integer multiples of the
+                                 sampling frequency, like 2x or 1x.
+                             
    • 
+                             
  • 
+                                 The bigger the time window, the higher the frequency precision,
+                                 but the lower the time resolution
+                             
    • 
+                             
  • 
+                                 The smaller the time window, the lower the frequency precision,
+                                 and the higher the time resolution
+                             
    • 
+                         

+                         

+                         

+                         

+                             For the S-Transform, there is only one single big window which
+                             is the full time range to be analyzed.
+                         

+                         

+                             See this note about time frequency issues.
+                     

+                         

+                             Windows Step:
+                     

+                         

+                             How much stepping to do when fetching the next time window:
+                         

+                         
    
+                             
  • 
+                                 
    
+                                     1 TF: one time frame, the shortest step,
+                                 
    
+                             
  • 
+                                 
    
+                                     25% Window: 25% of the window size is used, which means 25% of
+                                     new data incorporated,
+                                 
    
+                             
  • 
+                                 
    
+                                     100% Window: step across the whole current window, without any overlap.
+                                 
    
+                         

+                         

+                              
+                         

+                         

+                             Note that a 1 TF step is equivalent to perform a 
+                                 
+                                     Short
+                                     Term Fourier Transform
+                                  (STFT)
+                             .
+                         

+                         

+                             A 25% step (BTW used to be 75% overlap) is a safe way to add
+                             significantly new data to the time window.
+                         

+                         

+                             A 100% step is useful in case you have epochs pasted into a single
+                             file, and you shouldn't mix their data. So setting the window size to
+                             the epoch length, and stepping 100% is the way to go.
+                     

+                         

+                             windows step ... [ms]
+                     

+                         

+                             Showing the resulting step in [ms] between successive time windows.
+                     

+                         

+                             Number of Window(s):
+                     

+                         

+                             Showing the number of time windows you get with the current parameters.
+                         

+                         

+                             If the S-Transform analysis is used, there is only 1 window which
+                             extends exactly on the time range selected above.
+                     

+                         

+                             Frequencies
+                     

+                         

+                              
+                     

+                         

+                             Sampling Frequency:
+                     

+                         

+                             The current sampling frequency, if available from the current file.
+                         

+                         

+                             If in Batch mode, however, this field can and should be filled by hand.
+                     

+                         

+                             Frequency Range and Resolution:
+                     

+                         

+                             The range of frequencies and the frequency step/resolution
+                             you can obtain with your current parameters (Sampling Frequency and
+                             Window Size).
+                         

+                         

+                             For example, if step is 0.5 Hz,
+                             frequencies actually available will be: 0, 0.5, 1, 1.5 etc... Hz.
+                     

+                         

+                             Saving Frequency Interval:
+                     

+                         

+                             Specify a single interval of frequencies to be saved in
+                             the output file. Give the lowest and the highest frequencies of the
+                             interval, plus a step/resolution.
+                         

+                         

+                             The saved frequency steps can be bigger than the minimum available,
+                             f.ex. you can save by steps of 1 Hz even if the analysis offers you a
+                             0.5 Hz resolution. In this case Cartool will 
+                                 average
+                                 neighboring frequencies
+                             , therefore increasing the signal to
+                             noise ratio.
+                         

+                         

+                              
+                         

+                         

+                             Remember that it is always a good idea to constrain the 
+                                 saved frequency
+                                 range to be as small as possible
+                              according to your data. Otherwise
+                             you will have bigger and slower files, and for no use.
+                     

+                         

+                             Log Frequencies:
+                     

+                         

+                             Frequencies are inherently logarithmic by nature. For small ranges of
+                             frequencies, or to comply with usages, the whole interval of frequencies
+                             is often used. But for more accurate, or for broader ranges of
+                             frequencies, it is highly recommended to use a logarithmic scale instead.
+                         

+                     

+                         

+                             split into XX per Decade
+                     

+                         

+                             This tells how many subdivisions to save per decades (frequencies
+                             multipled by 10).
+                         

+                         

+                             F.ex. 20 values per decade means:
+                         

+                         
    
+                             
  • 20 frequency values for interval 1 to 10 [Hz]
    • 
+                             
  • 20 frequency values for interval 10 to 100 [Hz]
    • 
+                             
  • etc..
    • 
+                         

+                     

+                         

+                             Saving Frequency Bands:
+                     

+                         

+                             Save any number of bands, computing the average for each
+                             of them.
+                         

+                         

+                             Give the list of bands, separated either by a space, a comma or
+                             semi-colon. Be careful to actually order the bands: Cartool
+                             will follow the exact sequence you specify, so keep things consistant by
+                             using increasing frequency bands!
+                         

+                         

+                             F.ex.:  0-4, 4-8, 8-12, 12-20
+                         

+                         

+                             See this note about averaging frequencies.
+                     

+                         

+                             Type of Analysis
+                     

+                         

+                             You can choose between 3 well proven and robust analysis:
    
+                                 
  • FFT
    • 
+                                 
  • FFT Approximation
    • 
+                                 
  • Wavelet (S-Transform)
    • 
+                             

+                     

+                         

+                             

+                                 FFT
+                     

+                         

+                             The classical FFT, or the STFT (Short Term Fourier
+                             Transform) if the Windows Step parameter is set to 1 TF.
+                         

+                         

+                             With Average Reference data and saving the Square Norm, you can
+                             compute the Power Maps on surface recordings (see the Presets).
+                     

+                         

+                             

+                                 FFT Approximation
+                     

+                         

+                             Projection on the least-square deviation line going through the FFT
+                             for each window (of the average-referenced data), aka best dipole
+                             fitting. Results are in the "real" values, and will look
+                             like an EEG with polarity (see the Presets).
+                         

+                         

+                             See this note about averaging FFT approximation.
+                     

+                         

+                             

+                                 S-Transform
+                     

+                         

+                             The Stockwell Transform allows for some optimal time and frequency resolution.
+                         

+                         

+                             Note that it applies only to a single window, which can be as big as
+                             needed by your analysis. However to reduce the computational cost,
+                             and for big ranges, use rather the plain FFT and keep the S-Transform
+                             for shorter time ranges (like a magnifier on a given area).
+                     

+                         

+                             FFT Windowing Function:
+                     

+                         

+                              
+                     

+                         

+                             None
+                     

+                         

+                             No windowing function added (or, to be totally precise, using a Flat Top
+                             windowing function).
+                     

+                         

+                             Hanning
+                     

+                         

+                             Hanning windowing function. Try this
+                             to learn more. Also see this technical point.
+                         

+                             Recommended most of the time, except if you have no overlap between
+                             windows, or a a single time window.
+                     

+                         

+                             Time Windows are:
+                     

+                         

+                              
+                     

+                         

+                             Averaged
+                     

+                         

+                             Analysed windows are averaged, hence the result will be a single
+                             "Time Point". See this note
+                             about the averaging.
+                     

+                         

+                             in Sequence
+                     

+                         

+                             Analysed windows are written sequentially, so you can have an idea of
+                             the frequencies in time. See this note
+                             about the time reference.
+                     

+                         

+                             FFT Time Windows Rescaling:
+                     

+                         

+                             The FFT formula includes specifies a normalization, or divisive factor.
+                             Problem is there is no agreement on which formula to use in practice.
+                             Here you can specify the one to your liking:
    
+                                 
  • None: no rescaling at all
    • 
+                                 
  • Square Root of Time Window size
    • 
+                                 
  • 
+                                     Time Window size, aka Parseval formula.
+                                         
    
+                                         This is the most correct one, so if you don't know any better, keep
+                                         this option!
+                                         
+                                 
    • 
+                             

+                         

+                         

+                             Note: this option is relevant only for single forward FFT's,
+                             and not for the S-Transform (which is a forward + backward FFT all in
+                             one!)
+                     

+                         

+                             Outputting Values:
+                     

+                         

+                             Results of the analysis are always complex values. Usage is to
+                             save only the norm or power of these complex values, but you can still
+                             control what to actually save according to your needs:
    
+                                 
  • 
+                                     Real part
    Only the real part of the complex
+                                     value. Only available for the FFT Approximation analysis, though.
+                                 
    • 
+                                 
  • Norm
    The norm, or intensity of the results.
    • 
+                                 
  • 
+                                     Power (Squared Norm)
    The square of the norm,
+                                     or the power of the results. Quite the default.
+                                 
    • 
+                                 
  • 
+                                     Complex
    The complete complex values, written
+                                     following the C style (double real + double imag).
+                                 
    • 
+                                 
  • 
+                                     Phase
    The phase of the values, in the [0 ..
+                                     2Pi) range
+                                 
    • 
+                             

+                     

+                         

+                             Reference of Data
+                     

+                         

+                              
+                     

+                         

+                             No Reference
+                     

+                         

+                             Use the same reference as when the file(s) was(were) written, that
+                             is, no change in reference.
+                     

+                         

+                             Use Current Reference
+                     

+                         

+                             Use the reference currently in use. Useful only if the files have
+                             already been opened in Cartool, and the user has changed the reference.
+                     

+                         

+                             Average Reference
+                     

+                         

+                             Use the average reference,
+                             overriding current reference.
+                     

+                         

+                             Other Reference
+                     

+                         

+                             Use the average of the specified list of electrodes. If only
+                             one electrode is specified, this will be the reference.
+                     

+                         

+                             Options
+                     

+                         

+                              
+                     

+                         

+                             Optional filename infix override:
+                     

+                         

+                             The saved filenames will have the specified characters inserted.
+                             Default is a combination of the type of analysis and frequency range,
+                             which can be long and clumsy for your use.
+                     

+                         

+                             All Results in Single freq File
+                     

+                         

+                             This is the default ouput, a binary file
+                             holding all the results (frequencies, electrodes, and all time windows).
+                         

+                         

+                             Use this to save space on your disk, and / or to later use the 
+                                 Frequency
+                                 Display
+                              of Cartool.
+                     

+                         

+                             All Results in a Sub-Directory
+                     

+                         

+                             Optionally saving all results in a sub-directory for a better
+                             organization. Kind of hand if you wish to split the data with the
+                             splitting options below.
+                     

+                         

+                             Open File(s) Upon Completion
+                     

+                         

+                             ...of the analysis. Just be careful in 
+                                 Batch
+                                 Mode
+                             , this could open a lot of files! (the original EEG files
+                             are opened one at a time, then closed when done).
+                     

+                         

+                             Splitting Results:
+                     

+                         

+                             Frequency analysis results are 3D data by nature: electrodes x time x
+                             frequencies. To facilate either the display, the export or the processing
+                             with other toolboxes, it comes in handy to split these data into
+                             smalller, 2D files.
+                         

+                         

+                         

+                         

+                             Note: You can always 
+                                 
+                                     break
+                                     down .freq files
+                                 , or 
+                                     merge 2D files back into
+                                     .freq files
+                                 
+                              later on.
+                         

+                     

+                         

+                             

+                                 By Electrode
+                     

+                         

+                             Splitting results with one file per electrode.
+                         

+                     

+                         

+                             

+                                 By Frequency
+                     

+                         

+                             Splitting results with one file per frequency.
+                         

+                     

+                         

+                             

+                                 By Spectrum
+                     

+                         

+                             Splitting results with one file per spectrum.
+                         

+                         

+                             If you process sequentially
+                             the different time windows, there will be as many output files
+                             as there are of these time windows.
+                         

+                         

+                             If you average the time
+                             windows, a single file with the average spectrum is produced.
+                     

+                         

+                             Shrinking file size by.. Downsampling to Highest Freq.
+                     

+                         

+                             Especially useful for the S-Transform, the resulting files might very big
+                             and carrying way too much temporal information. F.ex. if the analyzed
+                             frequencies were in the range [5..50], you don't really care for time
+                             steps smaller than 20 [ms]. This option will optimally downsample the
+                             time resolution according to your parameters.
+                         

+                             Don't use it however if you wish to preserve a per time frame
+                             correspondance with your original data, though.
+                     

+                         

+                             Process Current
+                     

+                         

+                             Enabled when called from an EEG. The analysis applies only to 
+                                 this
+                                 current file
+                             .
+                         

+                         

+                             This button remains 
+                                 disabled until all the parameter
+                                 dialogs have received enough (and consistent) informations
+                             . If
+                             this is not the case, first check the current dialog: if its
+                             "Next" button is disabled, the problem is in the current
+                             dialog. Otherwise, browse the other dialogs for some missing informations.
+                     

+                         

+                             Batch Process
+                     

+                         

+                             Enabled when not called from an EEG. This will open a dialog for you
+                             to pick the set of files (even from different directories) to
+                             be analysed.
+                         

+                         

+                             This button remains 
+                                 disabled until all the parameter
+                                 dialogs have received enough (and consistent) informations
+                             . If
+                             this is not the case, first check the current dialog: if its
+                             "Next" button is disabled, the problem is in the current
+                             dialog. Otherwise, browse the other dialogs for some missing informations.
+                         

+                         

+                             You can Drag & Drop files directly to run the Batch Process!
+                     

+                         

+                             Cancel
+                     

+                         

+                             Quit the dialog.
+                     

+                         

+                             Help
+                     

+                         

+                             Launch the Help to the right page (should be here...).
+                     

+         

+         

+             Frequency analysis - Results
+         

+         
    
+             
  • 
+                 
    
+                     .freq file with
+                     all the important informations, if this option
+                     has been selected (of course recommended!). Freq files are written in
+                     the same directories as their sources. Open
+                     them to work with the results.
+                 
    
+             
  • 
+                 
    
+                     .sef files for each
+                     split electrode, frequency or spectrum, if any of splitting options have
+                     been used.
+                 
    
+             
  • 
+                 
    
+                     .ApproxEeg.ep
+                     file(s), for the approximated EEG of each electrode, for each saved
+                     time window (if the "Spectrum" option above has been
+                     selected). Note that these files also have the 
+                         frequencies on the
+                         horizontal axis
+                     , like the Spectrum.
+                 
    
+             
  • 
+                 
    
+                     Verbose file ...<type of analysis>.vrb 
+                     (text), showing all the parameters.
+                 
    
+         

+         

+             FFT Approximation
+         

+         

+             The FFT Approximation is a very convenient way
+             to retrieve an EEG-like signal, made of signed values, from
+             the FFT results.
+         

+         

+             To begin with, the FFT, when applied to a time window, always returns
+             results in the Complex space C. Each electrode, for each
+             frequency, is a complex number made of two parts, the real and
+             imaginary values. Hence, we can plot them on a plane (X is the real
+             axis, Y is the imaginary axis), here for one time window, and three
+             successive frequencies:
+         

+         

+             
+         

+         

+              
+         

+         

+             The FFT Approximation finds the best fitting line in the
+             average referenced data (equivalent to the best fitting dipole), then projects
+             the electrodes complex values on this axis. Being left with a single
+             dimension, a line, we arbitrarily assign a polarity to one direction,
+             and voilà, we have 
+                 real,
+                 signed, scalar values
+             . See again the same three frequencies, for
+             one time window, with the resulting projected electrodes:
+         

+         

+             
+         

+         

+              
+         

+         

+             We repeat this operation for each time window, see here the first 
+                 three
+                 time windows
+             , for a single frequency (see the rotating pattern
+             due to phase shift of the signal):
+         

+         

+             
+         

+         

+              
+         

+         

+             You may have noted that the final polarity is arbitrary, which should
+             be accounted for in case of averaging.
+             As long as patterns / topographies are concerns, this is not a real
+             problem, though.
+         

+         

+             Frequency analysis - Technical points
+         

+         

+             Files that can be processed
+         

+         

+             Input files can be anything that looks like tracks:
+         

+         
+         

+             Reference of data
+         

+         

+             Be aware that changing the reference of the data 
+                 greatly
+                 affects the shape of the signal
+             , and therefor its frequencies.
+             This is why the Power Maps and FFT Approximation
+             presets activate the average reference (as well as some other
+             parameters), to prevent any accidental change.

+             By the way, don't use these two methods for intra-cranial electrodes,
+             this does not make sense at all (again, see article)!
+         

+         

+             Time reference for each window
+         

+         

+             Each window is a part cut from the original file, say from  t 
+             to  t + window_size - 1. Once processed, the results are 
+                 frequencies
+                 for that whole window
+             . Therefor, it is natural to attribute the 
+                 mean
+                 time
+               t + window_size / 2  of that window as
+             its time position in the output file.
+         

+         

+             Averaging windows
+         

+         

+             Average occurs at the very last stage of the processing. For example, after
+             the Power Maps have been computed. This is not equivalent to
+             the Power Maps of the mean FFT.
+         

+         

+             Windowing function
+         

+         

+             When using the Hanning windowing function, the results after analysis
+             are multiplied by a factor 2 to account for the fading
+             introduced by the method.
+         

+         

+             Time / frequency resolution issue
+         

+         

+             Smaller time windows gives a higher time resolution,
+             but a lower frequency resolution. Conversely, bigger time
+             windows gives a lower time resolution, and a higher frequency
+             resolution. The dialog, by default, suggest a compromise between the
+             time and frequency resolution, which the user can change.
+         

+         

+             Here you can see the same time range analysed with a small (64), a
+             medium (256) and a large (1024) time window (for a sampling frequency
+             of 256 Hz):
+         

+         

+             

+             

+             
+         

+         

+             Averaging frequencies together
+         

+         

+             Frequencies saved and computed
+             usually differ, in the sense that often, 
+                 more frequencies are
+                 available from the transformation than there will be written to file
+             .
+             The most obvious case is when saving a frequency band, all
+             frequencies within that band will be averaged together into a single
+             result. Though, it also applies to the interval case, f.ex. if the
+             saved frequencies are stepping by 1 Hz, and the transformation allows
+             finer steps of 0.5 Hz.
+         

+         

+             To take benefit from that situation, 
+                 Cartool will average as much
+                 as it can from the available frequencies
+              to produce the requested
+             output results. Let's see how this works.
+         

+         

+             In the frequency band case:
+         

+         
    
+             
  • 
+                 
    
+                     All frequencies within the specified range (including both limits),
+                     with all the available steps (say, again, 0.5 Hz) will be averaged together.
    
+             
  • 
+                 But if the available steps are smaller than 0.25
+                 Hz, f.ex. 0.125 Hz, the steps taken will be limited to those
+                 multiples of 0.25 Hz. Stated otherwise, Cartool averages up to 0.25
+                 Hz steps.
    
+             
  • 
+                 In the S-Transform case, the number of
+                 frequencies averaged together has been limited to a total of 25 per
+                 band. Because the S-Transform is very smooth, and it does not provide
+                 much informations to average more, and because this transformation is
+                 very costly!
    
+         

+         

+             F.ex.: band 3-8 Hz, with steps of 0.5 Hz, will average frequencies 3,
+             3.5, 4, 4.5, 5, 5.5, 6, 6.5, 7, 7.5 and 8 Hz.
+         

+         

+              
+         

+         

+             In the interval case:
+         

+         
    
+             
  • 
+                 
    
+                     You have to specify a range of frequencies, plus a step to save. If
+                     your step is greater than the transformation available step, an
+                     averaging will occur. F.ex. you ask from 3 to 8 Hz, by steps of 1 Hz,
+                     but the resolution allows up to 0.25 Hz, then frequencies 3, 3.25,
+                     3.5 and 3.75 are averaged together for your first saved frequency.
+                     Then 4, 4.25, 4.5 and 4.75 for your second saved frequency etc...
+                     Stated otherwise, they are treated like a serie of small bands.
    
+             
  • 
+                 As for the band case, averaged steps will be
+                 limited to a minimum of 0.25 Hz.
    
+             
  • 
+                 As for the band case, the number of
+                 frequencies averaged together for the S-Transform for each step is
+                 also limited to 25 (but this is quite unlikely to happen!).
    
+         

+         

+              
+         

+         

+             In any case, you can see in the verbose file what are 
+                 exactly
+                 the frequencies that have been averaged together
+             , if you have
+             any doubt.
+         

+         

+             FFT Approximation and averaging
+         

+         

+             FFT Approximation results can also be averaged, as 
+                 explained
+                 here
+             . However some more checkings are to be done.
+         

+         

+             The problems arise from the fact that the results are signed, real values,
+             as an actual EEG would look like. However, during the FFT
+             Approximation process, the polarity of each map
+             has been assigned to an arbitrary value: a map can be either m
+             or -m, we can not know. This is an important issue when
+             averaging together these maps, as to avoid them to cancel each other
+             for this sign reason.
+         

+         

+             Thus, Cartool, when dealing with averaging FFT Approximation maps,
+             will perform 
+                 sign inversions of the maps whose correlation with
+                 each others are negative
+             . After the sign inversion the regular
+             summation can take place.
+         

+         

+             Averaging is done after conversion
+         

+         

+             When averaging many frequencies together (either 
+                 this
+                 case
+              or this case), the averaging
+             takes place after converting the results from complex to real
+             values, usually by taking the norm, the squared norm of the results,
+             or through the FFT Approximation.
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+     

  
 
\ No newline at end of file
diff --git a/docs/ReferenceGuide/frequency-display.html b/docs/ReferenceGuide/frequency-display.html
index 1905eba0..4827be10 100644
--- a/docs/ReferenceGuide/frequency-display.html
+++ b/docs/ReferenceGuide/frequency-display.html
@@ -2,725 +2,1071 @@
  
   Frequency Display
  
- 
-  

-   Frequency Display

-  

-    

-  

-   The Frequency Display tries to ease your job of browsing through 
-   frequencies, after the Frequency Analysis 
-   has been done.

-   The most important buttons are the 5 first ones, which, 
-   combined together, help you choose through a total of 8
-    different display modes.

-  

-   (Also note that the Frequency display is an extension of the EEG
-    display, so please refer to it for all their common parts)

-  

-   Buttons

-  

-   Most of the EEG Buttons +

-  

-   Display modes:

-  

-    

-  

-     

-  

-   Mouse

-  

-   Time navigation
Frequency navigation

-  

-   Keyboard

-  

-   Time navigation

-   Frequency navigation

-  

-   Menus

-  

-   Options

-  

-   Technical points

-  

-   Time considerations

-   Time & Frequency Cursors

-   Color scheme

-   Frequency normalization

-   Frequencies auto-scaling

-   Quality of display & Copy as Bitmap

-  

-   More on displays with frequencies

-  

-   Showing the frequencies as maps

-   Showing the frequencies geometrically distributed

-   Linking and superimposing frequencies 
-   from other files

-  

-   Frequency - Buttons

-  

-   Display modes

-  

-    

-  

-   These 5 buttons are the main switches to choose the type of display:

-  
    
-   
  • 
-   
    
-    The first 3 select how to project and lay down the 3 
-    dimensional data ( electrodes x frequencies x time ) onto a 2D display.
    
-    
  • The last 2 buttons simply add variations on 
-    the current layout, either by averaging some data, or 
-    switching between tracks and intensity displays.
    
-   

-  

-   Just play around with these switches, and see...

-  

-   Mode Spectrum  

-  

-   This is the well-known Spectrum display. The electrodes are on 
-   the vertical axis, and the frequencies are on the horizontal one.

-  

-   According to the Averaging button 
-   state, the display is either the mean spectrum, or a sequence
-    of spectrums:

-  
-  

-   Mode Electrodes / Frequencies  

-  

-   Displaying all the Frequencies for each Electrodes.

-  

-   The Averaging button and the Tracks
-    / Intensity button states affect the display in the 
-   following ways:

-  
-  

-   Mode Frequencies / Electrodes  

-  

-   Displaying all the Electrodes for each Frequencies, reversing the 
-   arrangement of Mode E / F.

-  

-   This one mode is useful to compare electrodes latencies for each 
-   frequency separately.

-  

-   The Averaging button and the Tracks
-    / Intensity button states affect the display in the 
-   following ways:

-  
-  

-   Averaging  

-  

-   Average / Enumerate the last dimension displayed, which 
-   depends on the current mode:

-  
-  

-   Let's have an example: the Spectrum display shows the frequencies 
-   for each electrode, the remaining dimension is therefor time.
-    If the Average button is On, then all time frames selected will be 
-   averaged together, giving the Average Spectrum (nothing to be scared 
-   of, you see?).

-  

-   

-  

-   Tracks / Bars / Intensity 
-   display  

-  

-   According to the current mode, this button 
-   lets use choose between Tracks (line plots), Bars 
-   (filled) and Intensity (colors) displays:

-  

-   

-  

-   Previous frequency  

-  

-   Moves the current frequency range to the previous frequency range, 
-   for example 5-14 Hz to 4-13 Hz. The actual value of the step 
-   depends on how the file was computed. If there is only one current 
-   frequency, and not a range, it behaves the same by shifting this frequency.

-   It has not effect if the range's lowest frequency has reached the 
-   minimum frequency of the data.

-  

-   See also Frequency navigation with the mouse,
-    and Frequency navigation with the keyboard.

-  

-   Next frequency  

-  

-   Moves the current frequency range to the next frequency range, for 
-   example 5-14 Hz to 6-15 Hz. The actual value of the step 
-   depends on how the file was computed. If there is only one current 
-   frequency, and not a range, it behaves the same by shifting this frequency.

-   It has not effect if the range's highest frequency has reached the 
-   maximum frequency of the data.

-  

-   See also Frequency navigation with the mouse,
-    and Frequency navigation with the keyboard.

-  

-   Less frequencies  

-  

-   Shrinks the actual frequency range by removing its highest frequency, 
-   f.ex. from 5-14 Hz to 5-13 Hz.

-   It has no effect if there remains only one frequency.

-  

-   See also Frequency navigation with the mouse,
-    and Frequency navigation with the keyboard.

-  

-   More frequencies  

-  

-   Expands the actual frequency range by adding one more frequency to 
-   its highest frequency, f.ex. from 5-14 Hz to 5-15 Hz. If the highest 
-   frequency has been reached, it continues expanding through the lower frequencies.

-   It has no effect if all frequencies are already selected.

-  

-   See also Frequency navigation with the mouse,
-    and Frequency navigation with the keyboard.

-  

-   Normalize power frequencies  

-  

-   When On, and whatever the current mode,
-    it will normalize the frequencies' power.

-  

-   It is a fact that low frequencies do have more powers than high ones. 
-   But we may be interested to see also the high frequencies' behavior. 
-   To cope with the intensity level differences, people usually simply increase
-    the global scaling of the whole display, or select a sub-range
-    of frequencies.

-  

-   But to allow seeing all the frequencies simultaneously, we need to counter-balance
-    the power differences across frequencies. Then only on the same 
-   display one can clearly see all the frequencies equally weighted. Power
-    doesn't account anymore, just the patterns of frequencies in time.
-    Stated otherwise, it allows you to see what changes in the frequencies.

-  

-   See here how Cartool does the estimation
-    of each frequency's power.

-  

-    

-  

-   Here are some examples, before and after frequency normalization:

-  
    
-   
  • 
-   
    
-    In this spectrum display, we discriminate 
-    better all the peaks in the high frequencies, and neutralize the 
-    lowest frequencies that don't change that much.
    
-   

-  

-   

-  
    
-   
  • 
-   
    
-    In this waterfall display, it behaves like a 
-    vertical adaptive scaling (filter), each frequency being 
-    independently rescaled. It tremendously helps in seeing where the 
-    signal changes, especially in the high frequencies.
    
-   

-  

-   

-  

-   Frequency - Mouse

-  

-   Quite the same as the EEG Mouse actions 
-   (some slight differences, though, as no Baseline
-    offset shifting is available).

-  

-   Time navigation

-  

-   If not in Spectrum display, the mouse 
-   will update the time cursor 
-   (shown in red), as usual.

-  

-   Frequency navigation

-  

-   If in Spectrum display, the mouse will update 
-   the frequency cursor (shown in 
-   blue), not the time cursor:

-  

-   

-  

-   If not in Spectrum display, by pressing  F  before 
-   a mouse operation, it will try to apply it to frequencies (when 
-   meaningful). F.ex. F + right 
-   click in a vertical motion will scroll through the frequency 
-   range, instead of scrolling through electrodes.

-  

-   See also Frequency navigation with the keyboard,
-    and Frequency navigation with buttons.

-  

-   Frequency - Keyboard

-  

-   Quite the same as the EEG 
-   Keyboard actions.

-  

-   Time navigation

-  

-   Whatever the mode you are currently in, the EEG
-    keys to navigate in time remain fully functional. F.ex. 
-   though in Spectrum display, pressing the left 
-   or right arrow keys will move the time cursor accordingly, and 
-   display the updated spectrum.

-  

-   Frequency navigation

-  

-   Whatever the mode you are currently in, by pressing  F 
-    before another key will try to apply the usual command to frequencies 
-   (when meaningful). F.ex. F + right arrow or down arrow would 
-   scroll downward through the frequency cursor.

-  

-   The  F  shortcut redirects the main functions of 
-   the time cursor to the frequency cursor.

-  

-    

-  

-   Another point, when trying to shift frequencies with the keyboard, 
-   which arrow keys you can use is contextual dependent. 
-   Use Left and Right arrow keys if the frequencies are on the X axis, 
-   Up and Down arrow keys if the frequencies are on the Y axis.

-  

-    

-  

-   See also Frequency navigation with the mouse,
-    and Frequency navigation with buttons.

-  

-   Frequency - Menus

-  

-   Quite the same as the EEG Menus, with the 
-   following variations or additions:

-  

-   Options menu

-  
    
-   
    
-    Reference
    
-   
      
-    
      
-     Has no effect, it has no meaning to change the "reference".
      
-    
    
-   
    
-    Reset frequency normalization
    
-   
-   
    
-    Show / hide 3D dimension description
    
-   
      
-    
      
-     All the time we are browsing in a 3 dimensions space (electrodes x 
-     frequencies x time). The main 2 dimensions for the current mode 
-     are clearly shown on the X and Y axis. The description of the 3d one 
-     is inserted inside the plotting, when enough space is available. But 
-     you can turn this information off.
      
-    
      
-      
      
-     Three examples from Mode E / F: electrodes y14 
-     and y5 (Y axis) in time (X axis), the 3d dimension is 
-     consequently frequency, 7/8/9 Hz on the first picture (enough 
-     space), 7 to 20 Hz (less space to display) on the second picture, and 
-     again on the third one but with the display turned off:
      
-    
      
-     
      
-    
    
-   

-  

-   Frequency - Technical points

-  

-   Time considerations

-  

-   Each time point, f.ex. in Mode E / F, is 
-   actually the center of the time window that was originally transformed.
-    Of course, after transformation you don't see it as a window 
-   anymore, as it has been splitted in different frequencies. Just 
-   remember that the time displayed in the title bar or cursor is the 
-   mean time of the time windows.

-  

-   In all modes except in Mode spectrum, time is 
-   represented on the X axis, as in an EEG display.
-    The time cursor is visible and is 
-   only a part of the display. You can update it through mouse 
-   or the keyboard operations.

-  

-   However, in the Mode spectrum, the time 
-   cursor is not visible. The spectrums currently shown are the 
-   one within the current time cursor only. Still you can update 
-   the time cursor, and instantly see the results, either:

-  
    
-   
  • 
-   
    
-    with Right and Left arrow keys
    
-    
  • by right clicking with an horizontal motion
    
-    
  • by moving the scrollbar below the window
    
-    
  • by changing the horizontal scale zoom, either with buttons,
-     keyboard or mouse.
    
-   

-  

-   Time and Frequency Cursors

-  

-   While browsing the data, there are always 2 active cursors, 
-   one for time (actually time windows) and one for frequencies.

-  

-   The first one is drawn in red, the second one in blue. Both
-    interact simultaneously with the current display, and by 
-   switching between modes you can conveniently modify one of the two 
-   cursors and instantly see the results.

-  

-   For example with frequencies 18-30 Hz and 4 windows selected (for a 
-   few electrodes to clarify the display), the frequencies on the left 
-   are the average of the 4 windows on the right, and the tracks on 
-   right are an average of the 13 frequencies of the left:

-  

-   

-  

-   See also the mouse operation.

-  

-   Color scheme

-  

-   If the display is showing tracks 
-   (i.e. not intensities), and in any mode,
-    a color scheme is applied to help you distinguish between frequencies.
-    A dark rainbow color table is matched to frequencies, with 
-   low frequencies assigned to dark red and high frequencies assigned to 
-   dark violet.This coloring is of course relative to the frequency span 
-   of the current file, and is not absolute.

-  

-   F.ex with frequencies on X axis and Y axis respectively:

-  

-   

-  

-   Frequency normalization

-  

-   It is well known that the power of the FFT follows a distribution 
-   that quickly decays with increasing frequencies. It has the huge 
-   disadvantage of hiding the high frequency peaks, and overemphasizing 
-   the low frequency ones (which may not be that interesting). The idea 
-   to overcome this effect is to normalize the power of each frequency,
-    so as to give each frequency the same weight. See here 
-   for some examples.

-  

-   Here is the idea used in Cartool, as we don't know in advance the 
-   power distributions:

-  
    
-   
  • 
-   
    
-    For each frequency, do:
-    
      
-     
    • Scan all electrodes and all time windows (up to 1024)
      
-     
    • Compute the Mean and SD of all (absolute) values
      
-     
    • Then compute a mean value only by selecting 
-     (absolute) values within the range Mean +- ( SD / 2 ), as to reject 
-     too weak and too strong signals
    
-    
  • With these mean powers for each frequency, inverse 
-    this curve, and normalize it.
    
-   

-  

-    

-  

-   See an example of the mean powers and the resulting normalization 
-   curve (frequencies are on the X axis):

-  

-   

-  

-   The time windows initally used are the first 1024 ones. But if it 
-   seems it does not represent well the data, you can re-apply
-    the frequency normalization anytime by using the current 
-   displayed time windows.

-  

-    

-  

-   You can judge if the normalization is doing its job correctly by 
-   looking to noisy data wihout signals, as you should see the same 
-   average intensity for all frequencies. See an example of 
-   "noisy" data vs interesting patterns that occur later on:

-  

-   

-  

-   Finally, note that the frequency normalization applies only on the display,
-    and does not alter the data.

-  

-   Frequencies auto-scaling

-  

-   Cartool provides a very convenient auto-scaling of the currrent 
-   displayed frequencies, at any time and in all modes.

-  

-   What is meant here is that the display always uses the strongest 
-   frequency to calibrate the maximum displayed. If you change which 
-   frequencies are shown, the new frequency maximum will be taken. In 
-   this way, you always have the most optimal display without having to 
-   change (much) your tunings. Also, don't be surprised when seeing some 
-   variations when browsing frequencies, this is the auto-scaling in action!

-  

-   An example here, the same display but with frequencies slightly 
-   shifted higher on the second picture. As the lowest (strongest) 
-   frequencies disappear from the display, the frequency auto-scaling 
-   re-adjust the maximum to the new available frequencies, thus making 
-   the new lowest ones look brighter:

-  

-   

-  

-   Well, that mechanism can not be turned off, FYI.

-  

-    

-  

-   Note: this is not to be misunderstood with the intensity
-    auto-scaling, which automatically adjusts the intensity maximum. 
-   But the combination of the two is very convenient, for sure.

-  

-   Quality of display & Copy as Bitmap

-  

-   Displaying in intensity modes (here and here)
-    is quite demanding in computer resources, especially with a lot of 
-   tracks. Cartool automatically and seemlessly adapts the quality of 
-   the display to allow reasonable display times. For examples, it 
-   simplifies the color drawing when a lot of tracks with a lot of 
-   frequencies are drawn. This could explain some strange changes you 
-   may see in the display.

-  

-   Though, when using Copy
-    as Bitmap, Cartool understands you are about to publish 
-   incredible results (yes, it does), so it will use the maximum quality.
-    The drawback is that you may have to wait a while (~10 secondes) 
-   until the end of the snapshot. You may also use this feature if you 
-   want to see all the finest details. Note that the high quality is 
-   automatically turned on when the tradeoff between the number 
-   of tracks and the time range displayed is acceptable.

-  

-   Here is an example of low versus high quality intensity display:

-  

-   

-  

-   More on displays with frequencies

-  

-   Displaying frequencies as maps

-  

-   Yes, you can do this, and it is straightforward! Through the link
-    mechanism, and by using freq files 
-   instead of EEG files, you can do exactly the same things as with EEG! 
-   F.ex. by adding some electrodes
-    coordinates file you get the maps of the current frequency.

-  

-   Move the frequency cursor to change 
-   the current displayed maps. For now, only the lowest frequency 
-   selected is shown, or the average selected frequencies if in
-    this mode.

-  

-   Here, f.ex., a FFT Approximation 
-   at 7.84 Hz linked with the electrodes coordinates, showing two 
-   different maps:

-  

-   
-    
-     
-     
-     
-    
-    
-     
-     
-     
-    
-    
-     
-     
-     
-    
-   

-      

-       

-      

-       

-         

-       

-      

-       

-         

-       

-      

-       

-         

-       

-      

-       

-        +

-      

-       

-      

-       

-        =

-      

-       

-      

-       

-         

-       

-      

-       

-         

-       

-      

-       

-         

-       

-      

-       

-        or

-      

-       

-  

-   Showing the frequencies 
-   geometrically distributed

-  

-   Again, with the same link
-    mechanism as above, you can show the frequencies geometrically
-    distributed according to the electrodes. Note that this is 
-   done directly within the frequency display.

-  

-   F.ex. in 2D here, some frequencies in time, 
-   and some waterfall:

-  

-   

-  

-   Linking and superimposing 
-   frequencies from other files

-  

-   As for EEGs, you can superimpose 
-   and compare data from other files in the current display
-    mode (well, doesn't work in Intensity
-    mode). Note that this is done directly within the frequency display.

-  

-   Here is an example of the spectrum of a given 
-   file, then the same spectrum (turned to black) with two other files 
-   on top of it (red and green respectively):

-  

-   

-  

-   You can change the display mode or any other 
-   parameters en route without problems while working with superimposed 
-   data. Although note a slight slow down if you link with too much files.

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    
+ 
+     

+         

+             Frequency Display
+         

+         

+              
+         

+         

+             The Frequency Display tries to ease your job of browsing through
+             frequencies, after the Frequency Analysis
+             has been done.

+             The most important buttons are the 5 first ones, which,
+             combined together, help you choose through a total of 
+                 
+                     8
+                     different display modes
+                 
+             .
+         

+         

+             (Also note that the Frequency display is an extension of the 
+                 
+                     EEG
+                     display
+                 
+             , so please refer to it for all their common parts)
+         

+         

+             Buttons
+         

+         

+             Most of the EEG Buttons +
+         

+         

+             Display modes:
+         

+         

+              
+         

+         

+               
+         

+         

+             Mouse
+         

+         

+             Time navigation
Frequency navigation
+         

+         

+             Keyboard
+         

+         

+             Time navigation

+             Frequency navigation
+         

+         

+             Menus
+         

+         

+             Options
+         

+         

+             Technical points
+         

+         

+             Time considerations

+             Time & Frequency Cursors

+             Color scheme

+             Frequency normalization

+             Frequencies auto-scaling

+             Quality of display & Copy as Bitmap
+         

+         

+             More on displays with frequencies
+         

+         

+             Showing the frequencies as maps

+             Showing the frequencies geometrically distributed

+             
+                 Linking and superimposing frequencies
+                 from other files
+             
+         

+         

+             Frequency - Buttons
+         

+         

+             Display modes
+         

+         

+              
+         

+         

+             These 5 buttons are the main switches to choose the type of display:
+         

+         
    
+             
  • 
+                 
    
+                     The first 3 select how to project and lay down the 
+                         3
+                         dimensional data ( electrodes x frequencies x time ) onto a 2D display
+                     .
    
+             
  • 
+                 The last 2 buttons simply add variations on
+                 the current layout, either by averaging some data, or
+                 switching between tracks and intensity displays.
    
+         

+         

+             Just play around with these switches, and see...
+         

+         

+             Mode Spectrum  
+         

+         

+             This is the well-known Spectrum display. The electrodes are on
+             the vertical axis, and the frequencies are on the horizontal one.
+         

+         

+             According to the Averaging button
+             state, the display is either the mean spectrum, or a 
+                 sequence
+                 of spectrums
+             :
+         

+         
+         

+             Mode Electrodes / Frequencies  
+         

+         

+             Displaying all the Frequencies for each Electrodes.
+         

+         

+             The Averaging button and the 
+                 
+                     Tracks
+                     / Intensity button
+                 
+              states affect the display in the
+             following ways:
+         

+         
+         

+             Mode Frequencies / Electrodes  
+         

+         

+             Displaying all the Electrodes for each Frequencies, reversing the
+             arrangement of Mode E / F.
+         

+         

+             This one mode is useful to compare electrodes latencies for each
+             frequency separately.
+         

+         

+             The Averaging button and the 
+                 
+                     Tracks
+                     / Intensity button
+                 
+              states affect the display in the
+             following ways:
+         

+         
+         

+             Averaging  
+         

+         

+             Average / Enumerate the last dimension displayed, which
+             depends on the current mode:
+         

+         
+         

+             Let's have an example: the Spectrum display shows the frequencies
+             for each electrode, the remaining dimension is therefor time.
+             If the Average button is On, then all time frames selected will be
+             averaged together, giving the Average Spectrum (nothing to be scared
+             of, you see?).
+         

+         

+             
+         

+         

+             Tracks / Bars / Intensity
+             display  
+         

+         

+             According to the current mode, this button
+             lets use choose between Tracks (line plots), Bars
+             (filled) and Intensity (colors) displays:
+         

+         

+             
+         

+         

+             Previous frequency  
+         

+         

+             Moves the current frequency range to the previous frequency range,
+             for example 5-14 Hz to 4-13 Hz. The actual value of the step
+             depends on how the file was computed. If there is only one current
+             frequency, and not a range, it behaves the same by shifting this frequency.

+             It has not effect if the range's lowest frequency has reached the
+             minimum frequency of the data.
+         

+         

+             See also Frequency navigation with the mouse,
+             and Frequency navigation with the keyboard.
+         

+         

+             Next frequency  
+         

+         

+             Moves the current frequency range to the next frequency range, for
+             example 5-14 Hz to 6-15 Hz. The actual value of the step
+             depends on how the file was computed. If there is only one current
+             frequency, and not a range, it behaves the same by shifting this frequency.

+             It has not effect if the range's highest frequency has reached the
+             maximum frequency of the data.
+         

+         

+             See also Frequency navigation with the mouse,
+             and Frequency navigation with the keyboard.
+         

+         

+             Less frequencies  
+         

+         

+             Shrinks the actual frequency range by removing its highest frequency,
+             f.ex. from 5-14 Hz to 5-13 Hz.

+             It has no effect if there remains only one frequency.
+         

+         

+             See also Frequency navigation with the mouse,
+             and Frequency navigation with the keyboard.
+         

+         

+             More frequencies  
+         

+         

+             Expands the actual frequency range by adding one more frequency to
+             its highest frequency, f.ex. from 5-14 Hz to 5-15 Hz. If the highest
+             frequency has been reached, it continues expanding through the lower frequencies.

+             It has no effect if all frequencies are already selected.
+         

+         

+             See also Frequency navigation with the mouse,
+             and Frequency navigation with the keyboard.
+         

+         

+             Normalize power frequencies  
+         

+         

+             When On, and whatever the current mode,
+             it will normalize the frequencies' power.
+         

+         

+             It is a fact that low frequencies do have more powers than high ones.
+             But we may be interested to see also the high frequencies' behavior.
+             To cope with the intensity level differences, people usually simply 
+                 increase
+                 the global scaling
+              of the whole display, or select a 
+                 sub-range
+                 of frequencies
+             .
+         

+         

+             But to allow seeing all the frequencies simultaneously, we need to 
+                 counter-balance
+                 the power differences across frequencies
+             . Then only on the same
+             display one can clearly see all the frequencies equally weighted. 
+                 Power
+                 doesn't account anymore, just the patterns of frequencies in time
+             .
+             Stated otherwise, it allows you to see what changes in the frequencies.
+         

+         

+             See here how Cartool does the 
+                 estimation
+                 of each frequency's power.
+             
+         

+         

+              
+         

+         

+             Here are some examples, before and after frequency normalization:
+         

+         
    
+             
  • 
+                 
    
+                     In this spectrum display, we discriminate
+                     better all the peaks in the high frequencies, and neutralize the
+                     lowest frequencies that don't change that much.
+                 
    
+         

+         

+             
+         

+         
    
+             
  • 
+                 
    
+                     In this waterfall display, it behaves like a
+                     vertical adaptive scaling (filter), each frequency being
+                     independently rescaled. It tremendously helps in seeing where the
+                     signal changes, especially in the high frequencies.
+                 
    
+         

+         

+             
+         

+         

+             Frequency - Mouse
+         

+         

+             Quite the same as the EEG Mouse actions
+             (some slight differences, though, as no 
+                 Baseline
+                 offset shifting
+              is available).
+         

+         

+             Time navigation
+         

+         

+             If not in Spectrum display, the mouse
+             will update the time cursor
+             (shown in red), as usual.
+         

+         

+             Frequency navigation
+         

+         

+             If in Spectrum display, the mouse will update
+             the frequency cursor (shown in
+             blue), not the time cursor:
+         

+         

+             
+         

+         

+             If not in Spectrum display, by pressing  F  before
+             a mouse operation, it will try to apply it to frequencies (when
+             meaningful). F.ex. F + 
+                 right
+                 click in a vertical motion
+              will scroll through the frequency
+             range, instead of scrolling through electrodes.
+         

+         

+             See also Frequency navigation with the keyboard,
+             and Frequency navigation with buttons.
+         

+         

+             Frequency - Keyboard
+         

+         

+             Quite the same as the 
+                 EEG
+                 Keyboard actions
+             .
+         

+         

+             Time navigation
+         

+         

+             Whatever the mode you are currently in, the 
+                 EEG
+                 keys to navigate in time
+              remain fully functional. F.ex.
+             though in Spectrum display, pressing the left
+             or right arrow keys will move the time cursor accordingly, and
+             display the updated spectrum.
+         

+         

+             Frequency navigation
+         

+         

+             Whatever the mode you are currently in, by pressing  F 
+             before another key will try to apply the usual command to frequencies
+             (when meaningful). F.ex. F + right arrow or down arrow would
+             scroll downward through the frequency cursor.
+         

+         

+             The  F  shortcut 
+                 redirects the main functions of
+                 the time cursor to the frequency cursor
+             .
+         

+         

+              
+         

+         

+             Another point, when trying to shift frequencies with the keyboard,
+             which arrow keys you can use is contextual dependent.
+             Use Left and Right arrow keys if the frequencies are on the X axis,
+             Up and Down arrow keys if the frequencies are on the Y axis.
+         

+         

+              
+         

+         

+             See also Frequency navigation with the mouse,
+             and Frequency navigation with buttons.
+         

+         

+             Frequency - Menus
+         

+         

+             Quite the same as the EEG Menus, with the
+             following variations or additions:
+         

+         

+             Options menu
+         

+         
    
+             
    
+                 Reference
+             
    
+             
      
+                 
      
+                     Has no effect, it has no meaning to change the "reference".
+                 
      
+             
    
+             
    
+                 Reset frequency normalization
+             
    
+             
+             
    
+                 Show / hide 3D dimension description
+             
    
+             
      
+                 
      
+                     All the time we are browsing in a 3 dimensions space (electrodes x
+                     frequencies x time). The main 2 dimensions for the current mode
+                     are clearly shown on the X and Y axis. The description of the 3d one
+                     is inserted inside the plotting, when enough space is available. But
+                     you can turn this information off.
+                 
      
+                 
      
+                      
      
+                     Three examples from Mode E / F: electrodes y14
+                     and y5 (Y axis) in time (X axis), the 3d dimension is
+                     consequently frequency, 7/8/9 Hz on the first picture (enough
+                     space), 7 to 20 Hz (less space to display) on the second picture, and
+                     again on the third one but with the display turned off:
+                 
      
+                 
      
+                     
+                 
      
+             
    
+         

+         

+             Frequency - Technical points
+         

+         

+             Time considerations
+         

+         

+             Each time point, f.ex. in Mode E / F, is
+             actually the center of the time window that was originally transformed.
+             Of course, after transformation you don't see it as a window
+             anymore, as it has been splitted in different frequencies. Just
+             remember that the time displayed in the title bar or cursor is the
+             mean time of the time windows.
+         

+         

+             In all modes except in Mode spectrum, time is
+             represented on the X axis, as in an EEG display.
+             The time cursor is visible and is
+             only a part of the display. You can update it through mouse
+             or the keyboard operations.
+         

+         

+             However, in the Mode spectrum, the time
+             cursor is not visible. The spectrums currently shown are the
+             one within the current time cursor only. Still you can update
+             the time cursor, and instantly see the results, either:
+         

+         
    
+             
  • 
+                 
    
+                     with Right and Left arrow keys
    
+             
  • by right clicking with an horizontal motion
    
+             
  • by moving the scrollbar below the window
    
+             
  • 
+                 by changing the horizontal scale zoom, either with buttons,
+                 keyboard or mouse.
    
+         

+         

+             Time and Frequency Cursors
+         

+         

+             While browsing the data, there are always 2 active cursors,
+             one for time (actually time windows) and one for frequencies.
+         

+         

+             The first one is drawn in red, the second one in blue. 
+                 Both
+                 interact simultaneously with the current display
+             , and by
+             switching between modes you can conveniently modify one of the two
+             cursors and instantly see the results.
+         

+         

+             For example with frequencies 18-30 Hz and 4 windows selected (for a
+             few electrodes to clarify the display), the frequencies on the left
+             are the average of the 4 windows on the right, and the tracks on
+             right are an average of the 13 frequencies of the left:
+         

+         

+             
+         

+         

+             See also the mouse operation.
+         

+         

+             Color scheme
+         

+         

+             If the display is showing tracks
+             (i.e. not intensities), and in any mode,
+             a color scheme is applied to help you distinguish between frequencies.
+             A dark rainbow color table is matched to frequencies, with
+             low frequencies assigned to dark red and high frequencies assigned to
+             dark violet.This coloring is of course relative to the frequency span
+             of the current file, and is not absolute.
+         

+         

+             F.ex with frequencies on X axis and Y axis respectively:
+         

+         

+             
+         

+         

+             Frequency normalization
+         

+         

+             It is well known that the power of the FFT follows a distribution
+             that quickly decays with increasing frequencies. It has the huge
+             disadvantage of hiding the high frequency peaks, and overemphasizing
+             the low frequency ones (which may not be that interesting). The idea
+             to overcome this effect is to normalize the power of each frequency,
+             so as to give each frequency the same weight. See here
+             for some examples.
+         

+         

+             Here is the idea used in Cartool, as we don't know in advance the
+             power distributions:
+         

+         
    
+             
  • 
+                 
    
+                     For each frequency, do:
+                     
      
+                         
    • Scan all electrodes and all time windows (up to 1024)
      
+                         
    • Compute the Mean and SD of all (absolute) values
      
+                         
    • 
+                             Then compute a mean value only by selecting
+                             (absolute) values within the range Mean +- ( SD / 2 ), as to reject
+                             too weak and too strong signals
+                     
    
+             
  • 
+                 With these mean powers for each frequency, inverse
+                 this curve, and normalize it.
    
+         

+         

+              
+         

+         

+             See an example of the mean powers and the resulting normalization
+             curve (frequencies are on the X axis):
+         

+         

+             
+         

+         

+             The time windows initally used are the first 1024 ones. But if it
+             seems it does not represent well the data, 
+                 you can 
+                     re-apply
+                     the frequency normalization
+                  anytime
+              by using the current
+             displayed time windows.
+         

+         

+              
+         

+         

+             You can judge if the normalization is doing its job correctly by
+             looking to noisy data wihout signals, as you should see the same
+             average intensity for all frequencies. See an example of
+             "noisy" data vs interesting patterns that occur later on:
+         

+         

+             
+         

+         

+             Finally, note that the frequency normalization applies only on the display,
+             and does not alter the data.
+         

+         

+             Frequencies auto-scaling
+         

+         

+             Cartool provides a very convenient 
+                 auto-scaling of the currrent
+                 displayed frequencies
+             , at any time and in all modes.
+         

+         

+             What is meant here is that the display always uses the 
+                 strongest
+                 frequency to calibrate the maximum displayed
+             . If you change which
+             frequencies are shown, the new frequency maximum will be taken. In
+             this way, you always have the most optimal display without having to
+             change (much) your tunings. Also, don't be surprised when seeing some
+             variations when browsing frequencies, this is the auto-scaling in action!
+         

+         

+             An example here, the same display but with frequencies slightly
+             shifted higher on the second picture. As the lowest (strongest)
+             frequencies disappear from the display, the frequency auto-scaling
+             re-adjust the maximum to the new available frequencies, thus making
+             the new lowest ones look brighter:
+         

+         

+             
+         

+         

+             Well, that mechanism can not be turned off, FYI.
+         

+         

+              
+         

+         

+             Note: this is not to be misunderstood with the 
+                 intensity
+                 auto-scaling
+             , which automatically adjusts the intensity maximum.
+             But the combination of the two is very convenient, for sure.
+         

+         

+             Quality of display & Copy as Bitmap
+         

+         

+             Displaying in intensity modes (here and here)
+             is quite demanding in computer resources, especially with a lot of
+             tracks. Cartool automatically and seemlessly 
+                 adapts the quality of
+                 the display
+              to allow reasonable display times. For examples, it
+             simplifies the color drawing when a lot of tracks with a lot of
+             frequencies are drawn. This could explain some strange changes you
+             may see in the display.
+         

+         

+             Though, when using 
+                 
+                     Copy
+                     as Bitmap
+                 
+             , Cartool understands you are about to publish
+             incredible results (yes, it does), so it will use the maximum quality.
+             The drawback is that you may have to wait a while (~10 secondes)
+             until the end of the snapshot. You may also use this feature if you
+             want to see all the finest details. Note that the 
+                 high quality is
+                 automatically turned on
+              when the tradeoff between the 
+                 number
+                 of tracks
+              and the time range displayed is acceptable.
+         

+         

+             Here is an example of low versus high quality intensity display:
+         

+         

+             
+         

+         

+             More on displays with frequencies
+         

+         

+             Displaying frequencies as maps
+         

+         

+             Yes, you can do this, and it is straightforward! Through the 
+                 
+                     link
+                     mechanism
+                 
+             , and by using freq files
+             instead of EEG files, you can do exactly the same things as with EEG!
+             F.ex. by adding some 
+                 electrodes
+                 coordinates file
+              you get the maps of the current frequency.
+         

+         

+             Move the frequency cursor to change
+             the current displayed maps. For now, 
+                 only the lowest frequency
+                 selected is shown
+             , or the average selected frequencies if 
+                 in
+                 this mode
+             .
+         

+         

+             Here, f.ex., a FFT Approximation
+             at 7.84 Hz linked with the electrodes coordinates, showing two
+             different maps:
+         

+         

+             
+                 
+                     
+                     
+                     
+                 
+                 
+                     
+                     
+                     
+                 
+                 
+                     
+                     
+                     
+                 
+             

+                         

+                             
+                     

+                         

+                             

+                                  
+                             

+                         

+                         

+                             

+                                  
+                             

+                         

+                         

+                             

+                                  
+                             

+                         

+                         

+                             

+                                 +
+                     

+                         

+                             
+                     

+                         

+                             

+                                 =
+                     

+                         

+                             
+                     

+                         

+                             

+                                  
+                             

+                         

+                         

+                             

+                                  
+                             

+                         

+                         

+                             

+                                  
+                             

+                         

+                         

+                             

+                                 or
+                     

+                         

+                             
+                     

+         

+         

+             Showing the frequencies
+             geometrically distributed
+         

+         

+             Again, with the same 
+                 
+                     link
+                     mechanism
+                 
+              as above, you can show the frequencies 
+                 
+                     geometrically
+                     distributed
+                 
+              according to the electrodes. Note that this is
+             done directly within the frequency display.
+         

+         

+             F.ex. in 2D here, some frequencies in time,
+             and some waterfall:
+         

+         

+             
+         

+         

+             Linking and superimposing
+             frequencies from other files
+         

+         

+             As for EEGs, you can superimpose
+             and compare data from other files in the current 
+                 display
+                 mode
+              (well, doesn't work in 
+                 Intensity
+                 mode
+             ). Note that this is done directly within the frequency display.
+         

+         

+             Here is an example of the spectrum of a given
+             file, then the same spectrum (turned to black) with two other files
+             on top of it (red and green respectively):
+         

+         

+             
+         

+         

+             You can change the display mode or any other
+             parameters en route without problems while working with superimposed
+             data. Although note a slight slow down if you link with too much files.
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+     

  
 
\ No newline at end of file
diff --git a/docs/ReferenceGuide/general-concepts.html b/docs/ReferenceGuide/general-concepts.html
index 22d60532..ff2ed312 100644
--- a/docs/ReferenceGuide/general-concepts.html
+++ b/docs/ReferenceGuide/general-concepts.html
@@ -2,559 +2,790 @@
  
   General Concepts
  
- 
-  

-   General Concepts

-  

-    

-  

-   Files and Views
Linking 
-   Files Together

-   Slave Windows

-  

-   Files and Views

-  

-   Opening files
Adding new views

-   Deleting views
Using views

-  

-   Opening files

-  

-   As with all programs, you can:

-  
    
-   
  • 
-   
    
-    Use drag and drop from the Explorer (the Chef's choice).
    
-   
  • 
-   
    
-    Menu File|Open, 
-    select the file type, then choose the file.
    
-   
  • 
-   
    
-    Double-click on the file from the Explorer. Note that in this case, 
-    you start a new running instance of Cartool, and having multiple 
-    Cartool running at the same time is not very memory efficient, though 
-    it will work. If it does not work or crashes? see here 
-    or here.
    
-   

-  

-   The file opens as a Document inside 
-   Cartool, with a default View attached to 
-   it. Then you can add new views to the 
-   document, that can be of different types of display, or delete
-    the views. When the last view is destroyed, the document is 
-   closed and removed from Cartool's memory.

-  

-   Adding new views

-  

-   You can add as many views to the same document as you wish, all 
-   showing the same data from the Document. You can use either:

-  
    
-   
  • 
-   
    
-    Press Control + A (the Chef's choice).
    
-    
  • Click on button.
    
-    
  • Menu Window
-     | Add View, and choose the view type if asked for it.
    
-   

-  

-   Deleting views

-  

-   Simply destroy the window by closing it.

-  

-   When the last View of a Document has been closed, the Document itself 
-   is closed, and removed from Cartool's memory.

-  

-   Using views

-  

-   Here is what you can do with all views:

-  
    
-   
  • 
-   
    
-    NumPad * will quickly inflate 
-    the window global size by 26% (repeated 3 times will make the 
-    window double in size)
    
-   
    
-    NumPad * + left or right arrow 
-    will quickly inflate the window horizontal size by 26%
    
-    NumPad * + up or down arrow 
-    will quickly inflate the window vertical size by 26%
    
-   
  • 
-   
    
-    NumPad / will quickly shrink 
-    the window global size by 26% (repeated 3 times will make the 
-    window half in size)
    
-   
    
-    NumPad / + left or right arrow 
-    will quickly shrink the window horizontal size by 26%
    
-    NumPad / + up or down arrow 
-    will quickly shrink the window vertical size by 26%
    
-   
  • 
-   
    
-    Letting the cursor on any button will bring a tool-tip window, 
-    giving a short message of its signification, and a keyboard shortcut. 
-    This is usually the most up-to-date help.
    
-   

-  

-   Linking Files Together

-  

-   Linking files is a key feature of Cartool, so it is very 
-   important to get used to it and to understand all the benefits you 
-   can get from it.

-  

-    

-  

-   What is "linking files"?

-   Link display explained
How to link files together

-   How to use the linked files

-   Creating new windows

-   Synchronization

-   More technical points

-  

-   What is "linking files"?

-  

-   Simply, it is binding together files that are in some way related 
-   and consistent relatively to each others. This is achieved 
-   (right now) through a simple listing in a .lm
-    file, and brings the following benefits:

-  
    
-   
  • 
-   
    
-    Avoiding and controlling information redundancy, for example 
-    by checking that all linked files do have the same number of 
-    electrodes, or that only one file contains the electrodes 
-    descriptions. F.ex. a link file containing 3 compatibles EEG files 
-    linked together with one electrode coordinates file:
    
-   
    
-    
    
-   
  • 
-   
    
-    Sharing informations between the linked files, for example all 
-    files will have access to the sampling frequency of the EEG, or the 
-    names of the electrodes even though they do not have these 
-    informations by themselves.
    
-   
  • 
-   
    
-    A consequence of the previous point, new
-     types of display are therefore available. Sharing 
-    information gives more powerful displays. F.ex. 1 EEG file plus 1 
-    electrode coordinates file can generate a spatial rendering of the potentials:
    
-   
    
-    The link file content itself:
    
-    
    
-    The 3 windows it can produce (EEG tracks, electrodes coordinates, 
-    scalp potentials):
    
-    +=>
    
-   
  • 
-   
    
-    Easily saving and managing your work for later use, as the 
-    files association is saved on disk.
    
-   
  • 
-   
    
-    Securing your data and results, as you know you always reopen 
-    the very same files, and can re-process your data with either the 
-    same parameters (for double-checking), or other parameters (for new 
-    trials). Absolute path is taken to differentiate between files 
-    with same file names, so be careful when moving files around.
    
-   
    
-    2 examples of link files, one putting a set of EEG files together, 
-    another one linking together everything you need for some inverse 
-    solutions, but without any EEG files:
    
-   
    
-    
    
-   

-  

-   Link display explained

-  

-   Here are the windows you will see when dealing with link files:

-  

-   

-    

-   

-  
    
-   
  • 
-   
    
-    Upper left is the link window itself, which lists all the 
-    files contained into the link. Double clicking on a file name will 
-    maximize or minimize the appropriate windows.
    
-   
  • 
-   
    
-    On its right, all the windows managed by this link. They do 
-    not belong to the link itself, as they are independent documents, but 
-    receive commands and share informations through the 
-    link mechanism.
    
-   
  • 
-   
    
-    The managed windows can be divided into 2 categories, the EEG 
-    "master" windows, and the other slave
-     windows. Slave windows depend of the EEG windows immediately 
-    on their left.
    
-   
  • 
-   
    
-    At the bottom, some windows opened and minimized to unclutter the display.
    
-   

-  

-   How to link files together

-  

-   Create a special file of type .lm,
-    with one of these way:

-  
    
-   
  • 
-   
    
-    Menu File|New 'Link Many' file,
-     which will straight away create an empty link file (but after you 
-    filled it, don't forget to save it on disk before closing Cartool!)
    
-   
  • 
-   
    
-    Menu File|New then 
-    selecting Link Many Files.
-     Some dialogs will pop out, asking for the files to be linked. When 
-    finished, the name of the link file is also asked, and saved to disk.
    
-   

-  

-    

-  

-   Update the link at any time with:

-  
    
-   
  • 
-   
    
-    Drag files from the Explorer and drop them inside the link window.
-     Regular files will be added directly. But dropping another link 
-    file will copy its content. A very useful way to use this is to 
-    have a set of predefined linked files, linking to often used files, 
-    that will be added on demand in a single operation. F.ex. 2 separate 
-    link files that merge together:
    
-   
    
-    dropped
-     into
    
-    generates
    
-    (the managed windows it may generate are 
-    not shown here)
    
-   
  • 
-   
    
-    From the link file window, press on 
-    the "Add files" button .
-     A "+" shaped cursor appears, click on the windows (within 
-    Cartool!) of already open files to include them on the fly. If you 
-    click on another link file, as in the previous point, all the files 
-    it contains will be transferred at once. Click in the background to 
-    stop linking..
    
-   

-  

-    

-  

-   On each addition of a new file, here is what happen in real time:

-  
    
-   
  • 
-   
    
-    The file is checked against all the others for all possible 
-    consistencies. F.ex. all number of electrodes or solution points 
-    should be the same across all files.
    
-    
  • If the check is successful, the file is accepted, 
-    and added to the link file.
    
-    
  • If a new type of display is available, due to these 
-    new incoming informations, a new window 
-    is created straight away (so you don't have to request it), and all 
-    the other windows are refreshed. So don't be surprised to see windows 
-    opening and shuffling all around your screen, just wait.
    
-    
  • Linked files are locked, and can not be 
-    individually closed, to prevent the link integrity. Closing the link 
-    file will remove all locks, and will also close the linked files.
    
-   

-  

-   How to use the linked files

-  

-   Once open, from the link window itself,
-    you can operate on the windows it manages:

-  
    
-   
  • 
-   
    
-    Tile
-     all managed windows by compacting the display, still keeping
-     current windows size.
    
-    
  • Tile
-     all managed windows by compacting the display, and assigning default
-     sizes to all windows.
    
-    
  • Tile
-     all managed windows by compacting the display, resizing 
-    all windows to fit in a single page.
    
-    
  • see
-     adding files.
    
-    
  • tosee
-     synchronization.
    
-    
  • will
-     call the segmentation procedure.
    
-    
  • In the link window itself, double clicking 
-    on a file name will maximize or minimize the appropriate windows.
    
-   

-  

-   Creating new windows

-  

-   More interesting is what you can do from any window
-    managed by the linked files (say, from an EEG window). As 
-   said earlier, informations are now shared amongst all the files. By requesting
-    a new view, a context sensitive list of currently available displays 
-   will pop out. See also the related topic on "slave
-    windows".

-  

-   Currently, here are the different types of windows (according to the 
-   link content):

-  
    
-   
  • 
-   
    
-    Tracks display, with new available renderings:
    
-   
    
-    
    
-   
  • 
-   
    
-    3D potentials display:
    
-   
    
-    
    
-   
  • 
-   
    
-    3D inverse solutions:
    
-   
    
-    
    
-   

-  

-   Synchronization

-  

-   The  Synchronizing 
-    menu, together with the following buttons, provide some predefined 
-   way to synchronize the managed slave
-    windows:

-  
    
-   
  • 
-   
    
-    Synchronize
-     all
    
-   
    
-    All windows are synchronized at once:
    
-    
    
-   
  • 
-   
    
-    Desynchronize
-     all
    
-   
    
-    Clear all synchronizations, all windows are independent again:
    
-    
    
-   
  • 
-   
    
-    Synchronize
-     only within same EEG
    
-   
    
-    Each EEG will synchronize all of its own slave
-     windows (create "horizontal" synchronizations):
    
-    
    
-   
  • 
-   
    
-    Desynchronize
-     between different EEGs
    
-   
    
-    Break any existing synchronizations between windows from different 
-    EEGs (break the "vertical" synchronizations). Still 
-    preserving existing "horizontal" synchronizations:
    
-    
    
-   
  • 
-   
    
-    Clone
-     user commands within likewise windows
    
-   
    
-    Once activated, (most) commands done in any window will 
-    spread to the other windows of the same type (f.ex. EEG to EEG, 
-    Potential Maps to Potential Maps, etc...). Simply put, it allows you 
-    not to repeat the tunings done in one window again in the others.
    
-   
    
-    The commands modifying the time cursor 
-    are not spread, because they are specifically handled by the 
-    synchronization process (see above).
-     Then through the right combination of settings, you can choose 
-    either to modify the setup of the windows, the time cursor, or both.
    
-   
    
-    Commands include left and right 
-    mouse operations (rotation, zoom, brightness and contrast), and 
-    all buttons (including keyboard shortcuts) except those that apply to time.
    
-   

-  

-   More technical points

-  

-   When opening a link file, Cartool will open all the files listed into 
-   it. Many of them will be straight away minimized to clean up a bit 
-   the display. Typically, the electrode coordinates, inverse solutions 
-   matrices, MRI's etc...

-  

-   Creating a new view from a given window will actually create as 
-   many views as there are EEG files, one for each of them. The new 
-   views will be assigned the rightmost position of all managed
-    windows.

-  

-   Slave Windows

-  

-   See the Linking files paragraph 
-   beforehand, as it applies to windows created within the link 
-   mechanism only.

-  

-    

-  

-   Windows in slavery...

-   Controlling your slave windows    

-  

-    

-  

-   Windows in slavery...

-  

-   All views managed by the link mechanism 
-   are not equals, the EEG display naturally leading all the 
-   others attached to it as it contains the source of the data flow,
-    thus being the "master". All the other windows are 
-   therefore "slaves" to it, and need at least one 
-   "master" for existing (see here 
-   for a summary of the various windows available).

-   F.ex. moving the cursor inside the EEG window (on the left, the 
-   master), will drive and update the scalp potentials window (on the 
-   right, the slave) in real time:

-  

-   

-   

-  

-    

-  

-   You can have for the same EEG as many windows as you want, 
-   just create them. New 
-   "slave" windows will be assigned the last EEG 
-   "master" window created. Two examples here show 1 tracks 
-   display and 3 potentials display associated, then 2 tracks display 
-   and respectively 2 and 1 potentials displays associated:

-  

-   

-   

-  

-   Note that the potential windows, though they usually share a single 
-   EEG tracks display, are independent one of the others. That means the time
-    cursor is moved only for this particular window.

-  

-   Controlling your slave windows

-  

-   Slave windows have a few extra controls over the world (a little compensation...):

-  
    
-   
  • 
-   
    
-     
-     Synchronizing with other slave windows,
-     a key feature of Cartool (See also the synchronizing
-     menu, to operate globally).
    
-   
    
-    A clock-like cursor appears, with which you can click on other slave 
-    windows, even from other link files. These windows will be time-synchronized,
-     so moving the cursor in any of them will update the cursor in all 
-    the others. F.ex. 3 windows before (independent cursors) and after (3 
-    cursors equals) synchronization:
    
-   
    
-    
    
-   
    
-    If 2 groups of windows, say { A, B, C } and { D, E } respectively are 
-    already synchronized, it is enough to synchronize f.ex. windows A and 
-    D to merge the 2 groups together, { A .. E } becoming synchronous 
-    ("Synchronicity is transitive").
    
-   
    
-    Synchronicity does account for different sampling frequency, so you 
-    can sync an EEG sampled at 1000Hz and another one sampled at 256Hz 
-    correctly. EEG lengths can also differ, the cursor being safely 
-    clipped to the limits of each EEGs.
    
-   
    
-    To stop the synchronizing process, click on the background.
    
-   
    
-    To desynchronize a window from all the others, click with the 
-    clock-like cursor on the window itself.
    
-   
    
-    By default, when opening a link file, all EEG windows synchronize all 
-    their "slave" windows with them. Simply means you can move 
-    the cursor, and see the result accordingly!
    
-   
  • 
-   
    
-     
-     Average the values of the EEG if the time
-     cursor spreads across multiple time frames, then show the result:
    
-   
    
-    
    
-   
  • 
-   
    
-     
-     Display a sequence of time frames if the time
-     cursor spreads across multiple time frames.
    
-   
    
-    Usually, there are more than one sequence layout available, 
-    just click again to toggle through all possibilities (the 
-    number of frames is controlled here):
    
-   
    
-    
    
-   
  • 
-   
    
-     
-     Run an animation if the time cursor 
-    spreads across multiple time frames. Click again to stop 
-    or restart the animation (speed is controlled here):
    
-   
    
-    
    
-   
  • 
-   
    
-     
-     In case of sequence or animation, reduce the number of 
-    frames, or the speed.
    
-   
  • 
-   
    
-     
-     In case of sequence or animation, increase the number of 
-    frames, or the speed.
    
-   

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    
+ 
+     

+         

+             General Concepts
+         

+         

+              
+         

+         

+             Files and Views

+                 Linking
+                 Files Together
+             

+             Slave Windows
+         

+         

+             Files and Views
+         

+         

+             Opening files
Adding new views

+             Deleting views
Using views
+         

+         

+             Opening files
+         

+         

+             As with all programs, you can:
+         

+         
    
+             
  • 
+                 
    
+                     Use drag and drop from the Explorer (the Chef's choice).
+                 
    
+             
  • 
+                 
    
+                     Menu File|Open,
+                     select the file type, then choose the file.
+                 
    
+             
  • 
+                 
    
+                     Double-click on the file from the Explorer. Note that in this case,
+                     you start a new running instance of Cartool, and having multiple
+                     Cartool running at the same time is not very memory efficient, though
+                     it will work. If it does not work or crashes? see here
+                     or here.
+                 
    
+         

+         

+             The file opens as a Document inside
+             Cartool, with a default View attached to
+             it. Then you can add new views to the
+             document, that can be of different types of display, or 
+                 delete
+                 the views
+             . When the last view is destroyed, the document is
+             closed and removed from Cartool's memory.
+         

+         

+             Adding new views
+         

+         

+             You can add as many views to the same document as you wish, all
+             showing the same data from the Document. You can use either:
+         

+         
    
+             
  • 
+                 
    
+                     Press Control + A (the Chef's choice).
    
+             
  • Click on button.
    
+             
  • 
+                 Menu 
+                     Window
+                     | Add View
+                 , and choose the view type if asked for it.
    
+         

+         

+             Deleting views
+         

+         

+             Simply destroy the window by closing it.
+         

+         

+             When the last View of a Document has been closed, the Document itself
+             is closed, and removed from Cartool's memory.
+         

+         

+             Using views
+         

+         

+             Here is what you can do with all views:
+         

+         
    
+             
  • 
+                 
    
+                     NumPad * will quickly inflate
+                     the window global size by 26% (repeated 3 times will make the
+                     window double in size)
+                 
    
+                 
    
+                     NumPad * + left or right arrow
+                     will quickly inflate the window horizontal size by 26%
    
+                     NumPad * + up or down arrow
+                     will quickly inflate the window vertical size by 26%
+                 
    
+             
  • 
+                 
    
+                     NumPad / will quickly shrink
+                     the window global size by 26% (repeated 3 times will make the
+                     window half in size)
+                 
    
+                 
    
+                     NumPad / + left or right arrow
+                     will quickly shrink the window horizontal size by 26%
    
+                     NumPad / + up or down arrow
+                     will quickly shrink the window vertical size by 26%
+                 
    
+             
  • 
+                 
    
+                     Letting the cursor on any button will bring a tool-tip window,
+                     giving a short message of its signification, and a keyboard shortcut.
+                     This is usually the most up-to-date help.
+                 
    
+         

+         

+             Linking Files Together
+         

+         

+             Linking files is a key feature of Cartool, so it is very
+             important to get used to it and to understand all the benefits you
+             can get from it.
+         

+         

+              
+         

+         

+             What is "linking files"?

+             Link display explained
How to link files together

+             How to use the linked files

+             Creating new windows

+             Synchronization

+             More technical points
+         

+         

+             What is "linking files"?
+         

+         

+             Simply, it is binding together files that are in some way related
+             and consistent relatively to each others. This is achieved
+             (right now) through a simple listing in a 
+                 .lm
+                 file
+             , and brings the following benefits:
+         

+         
    
+             
  • 
+                 
    
+                     Avoiding and controlling information redundancy, for example
+                     by checking that all linked files do have the same number of
+                     electrodes, or that only one file contains the electrodes
+                     descriptions. F.ex. a link file containing 3 compatibles EEG files
+                     linked together with one electrode coordinates file:
+                 
    
+                 
    
+                     
+                 
    
+             
  • 
+                 
    
+                     Sharing informations between the linked files, for example all
+                     files will have access to the sampling frequency of the EEG, or the
+                     names of the electrodes even though they do not have these
+                     informations by themselves.
+                 
    
+             
  • 
+                 
    
+                     A consequence of the previous point, 
+                         
+                             new
+                             types of display
+                          are therefore available
+                     . Sharing
+                     information gives more powerful displays. F.ex. 1 EEG file plus 1
+                     electrode coordinates file can generate a spatial rendering of the potentials:
+                 
    
+                 
    
+                     The link file content itself:
    
+                     
    
+                     The 3 windows it can produce (EEG tracks, electrodes coordinates,
+                     scalp potentials):
    
+                     +=>
+                 
    
+             
  • 
+                 
    
+                     Easily saving and managing your work for later use, as the
+                     files association is saved on disk.
+                 
    
+             
  • 
+                 
    
+                     Securing your data and results, as you know you always reopen
+                     the very same files, and can re-process your data with either the
+                     same parameters (for double-checking), or other parameters (for new
+                     trials). Absolute path is taken to differentiate between files
+                     with same file names, so be careful when moving files around.
+                 
    
+                 
    
+                     2 examples of link files, one putting a set of EEG files together,
+                     another one linking together everything you need for some inverse
+                     solutions, but without any EEG files:
+                 
    
+                 
    
+                     
+                 
    
+         

+         

+             Link display explained
+         

+         

+             Here are the windows you will see when dealing with link files:
+         

+         

+             

+                 
+             

+         

+         
    
+             
  • 
+                 
    
+                     Upper left is the link window itself, which lists all the
+                     files contained into the link. Double clicking on a file name will
+                     maximize or minimize the appropriate windows.
+                 
    
+             
  • 
+                 
    
+                     On its right, all the windows managed by this link. They do
+                     not belong to the link itself, as they are independent documents, but
+                     receive commands and share informations through the
+                     link mechanism.
+                 
    
+             
  • 
+                 
    
+                     The managed windows can be divided into 2 categories, the 
+                         EEG
+                         "master" windows
+                     , and the other 
+                         
+                             slave
+                             windows
+                         
+                     . Slave windows depend of the EEG windows immediately
+                     on their left.
+                 
    
+             
  • 
+                 
    
+                     At the bottom, some windows opened and minimized to unclutter the display.
+                 
    
+         

+         

+             How to link files together
+         

+         

+             Create a special file of type .lm,
+             with one of these way:
+         

+         
    
+             
  • 
+                 
    
+                     Menu File|New 'Link Many' file,
+                     which will straight away create an empty link file (but after you
+                     filled it, don't forget to save it on disk before closing Cartool!)
+                 
    
+             
  • 
+                 
    
+                     Menu File|New then
+                     selecting Link Many Files.
+                     Some dialogs will pop out, asking for the files to be linked. When
+                     finished, the name of the link file is also asked, and saved to disk.
+                 
    
+         

+         

+              
+         

+         

+             Update the link at any time with:
+         

+         
    
+             
  • 
+                 
    
+                     Drag files from the Explorer and drop them inside the link window.
+                     Regular files will be added directly. But dropping 
+                         another link
+                         file will copy its content
+                     . A very useful way to use this is to
+                     have a set of predefined linked files, linking to often used files,
+                     that will be added on demand in a single operation. F.ex. 2 separate
+                     link files that merge together:
+                 
    
+                 
    
+                     dropped
+                     into
    
+                     generates
    
+                     (the managed windows it may generate are
+                     not shown here)
+                 
    
+             
  • 
+                 
    
+                     From the link file window, press on
+                     the "Add files" button .
+                     A "+" shaped cursor appears, click on the windows (within
+                     Cartool!) of already open files to include them on the fly. If you
+                     click on another link file, as in the previous point, all the files
+                     it contains will be transferred at once. Click in the background to
+                     stop linking..
+                 
    
+         

+         

+              
+         

+         

+             On each addition of a new file, here is what happen in real time:
+         

+         
    
+             
  • 
+                 
    
+                     The file is checked against all the others for all possible
+                     consistencies. F.ex. all number of electrodes or solution points
+                     should be the same across all files.
    
+             
  • 
+                 If the check is successful, the file is accepted,
+                 and added to the link file.
    
+             
  • 
+                 If a new type of display is available, due to these
+                 new incoming informations, a new window
+                 is created straight away (so you don't have to request it), and all
+                 the other windows are refreshed. So don't be surprised to see windows
+                 opening and shuffling all around your screen, just wait.
    
+             
  • 
+                 Linked files are locked, and can not be
+                 individually closed, to prevent the link integrity. Closing the link
+                 file will remove all locks, and will also close the linked files.
    
+         

+         

+             How to use the linked files
+         

+         

+             Once open, from the link window itself,
+             you can operate on the windows it manages:
+         

+         
    
+             
  • 
+                 
    
+                     Tile
+                     all managed windows by compacting the display, still 
+                         keeping
+                         current windows size
+                     .
    
+             
  • 
+                 Tile
+                 all managed windows by compacting the display, and assigning 
+                     default
+                     sizes
+                  to all windows.
    
+             
  • 
+                 Tile
+                 all managed windows by compacting the display, 
+                     resizing
+                     all windows to fit in a single page
+                 .
    
+             
  • 
+                 see
+                 adding files.
    
+             
  • 
+                 tosee
+                 synchronization.
    
+             
  • 
+                 will
+                 call the segmentation procedure.
    
+             
  • 
+                 In the link window itself, double clicking
+                 on a file name will maximize or minimize the appropriate windows.
    
+         

+         

+             Creating new windows
+         

+         

+             More interesting is what you can do 
+                 from any 
+                     window
+                     managed by the linked files
+                 
+              (say, from an EEG window). As
+             said earlier, informations are now shared amongst all the files. By 
+                 requesting
+                 a new view
+             , a context sensitive list of currently available displays
+             will pop out. See also the related topic on "
+                 slave
+                 windows
+             ".
+         

+         

+             Currently, here are the different types of windows (according to the
+             link content):
+         

+         
    
+             
  • 
+                 
    
+                     Tracks display, with new available renderings:
+                 
    
+                 
    
+                     
+                 
    
+             
  • 
+                 
    
+                     3D potentials display:
+                 
    
+                 
    
+                     
+                 
    
+             
  • 
+                 
    
+                     3D inverse solutions:
+                 
    
+                 
    
+                     
+                 
    
+         

+         

+             Synchronization
+         

+         

+             The  Synchronizing 
+             menu, together with the following buttons, provide some predefined
+             way to synchronize the managed 
+                 slave
+                 windows
+             :
+         

+         
    
+             
  • 
+                 
    
+                     
+                         Synchronize
+                         all
+                     
+                 
    
+                 
    
+                     All windows are synchronized at once:
    
+                     
+                 
    
+             
  • 
+                 
    
+                     
+                         Desynchronize
+                         all
+                     
+                 
    
+                 
    
+                     Clear all synchronizations, all windows are independent again:
    
+                     
+                 
    
+             
  • 
+                 
    
+                     
+                         Synchronize
+                         only within same EEG
+                     
+                 
    
+                 
    
+                     Each EEG will synchronize all of its own 
+                         slave
+                         windows
+                      (create "horizontal" synchronizations):
    
+                     
+                 
    
+             
  • 
+                 
    
+                     
+                         Desynchronize
+                         between different EEGs
+                     
+                 
    
+                 
    
+                     Break any existing synchronizations between windows from different
+                     EEGs (break the "vertical" synchronizations). Still
+                     preserving existing "horizontal" synchronizations:
    
+                     
+                 
    
+             
  • 
+                 
    
+                     
+                         Clone
+                         user commands within likewise windows
+                     
+                 
    
+                 
    
+                     Once activated, (most) commands done in any window 
+                         will
+                         spread to the other windows of the same type
+                      (f.ex. EEG to EEG,
+                     Potential Maps to Potential Maps, etc...). Simply put, it allows you
+                     not to repeat the tunings done in one window again in the others.
+                 
    
+                 
    
+                     The commands modifying the time cursor
+                     are not spread, because they are specifically handled by the
+                     synchronization process (see above).
+                     Then through the right combination of settings, you can choose
+                     either to modify the setup of the windows, the time cursor, or both.
+                 
    
+                 
    
+                     Commands include 
+                         left and right
+                         mouse operations
+                      (rotation, zoom, brightness and contrast), and
+                     all buttons (including keyboard shortcuts) except those that apply to time.
+                 
    
+         

+         

+             More technical points
+         

+         

+             When opening a link file, Cartool will open all the files listed into
+             it. Many of them will be straight away minimized to clean up a bit
+             the display. Typically, the electrode coordinates, inverse solutions
+             matrices, MRI's etc...
+         

+         

+             Creating a new view from a given window will actually create 
+                 as
+                 many views as there are EEG files
+             , one for each of them. The new
+             views will be assigned the rightmost position of all 
+                 managed
+                 windows
+             .
+         

+         

+             Slave Windows
+         

+         

+             See the Linking files paragraph
+             beforehand, as it applies to 
+                 windows created within the link
+                 mechanism only
+             .
+         

+         

+              
+         

+         

+             Windows in slavery...

+             Controlling your slave windows    
+         

+         

+              
+         

+         

+             Windows in slavery...
+         

+         

+             All views managed by the link mechanism
+             are not equals, the EEG display naturally leading all the
+             others attached to it as it contains the source of the data flow,
+             thus being the "master". 
+                 All the other windows are
+                 therefore "slaves"
+              to it, and need at least one
+             "master" for existing (see here
+             for a summary of the various windows available).

+             F.ex. moving the cursor inside the EEG window (on the left, the
+             master), will drive and update the scalp potentials window (on the
+             right, the slave) in real time:
+         

+         

+             

+             
+         

+         

+              
+         

+         

+             You can have for the same EEG as many windows as you want,
+             just create them. New
+             "slave" windows will be assigned the last EEG
+             "master" window created. Two examples here show 1 tracks
+             display and 3 potentials display associated, then 2 tracks display
+             and respectively 2 and 1 potentials displays associated:
+         

+         

+             

+             
+         

+         

+             Note that the potential windows, though they usually share a single
+             EEG tracks display, are independent one of the others. That means the 
+                 time
+                 cursor
+              is moved only for this particular window.
+         

+         

+             Controlling your slave windows
+         

+         

+             Slave windows have a few extra controls over the world (a little compensation...):
+         

+         
    
+             
  • 
+                 
    
+                     
+                          
+                         Synchronizing
+                      with other slave windows,
+                     a key feature of Cartool (See also the 
+                         synchronizing
+                         menu
+                     , to operate globally).
+                 
    
+                 
    
+                     A clock-like cursor appears, with which you can click on other slave
+                     windows, even from other link files. These windows will be time-synchronized,
+                     so moving the cursor in any of them will update the cursor in all
+                     the others. F.ex. 3 windows before (independent cursors) and after (3
+                     cursors equals) synchronization:
+                 
    
+                 
    
+                     
+                 
    
+                 
    
+                     If 2 groups of windows, say { A, B, C } and { D, E } respectively are
+                     already synchronized, it is enough to synchronize f.ex. windows A and
+                     D to merge the 2 groups together, { A .. E } becoming synchronous
+                     ("Synchronicity is transitive").
+                 
    
+                 
    
+                     Synchronicity does account for different sampling frequency, so you
+                     can sync an EEG sampled at 1000Hz and another one sampled at 256Hz
+                     correctly. EEG lengths can also differ, the cursor being safely
+                     clipped to the limits of each EEGs.
+                 
    
+                 
    
+                     To stop the synchronizing process, click on the background.
+                 
    
+                 
    
+                     To desynchronize a window from all the others, click with the
+                     clock-like cursor on the window itself.
+                 
    
+                 
    
+                     By default, when opening a link file, all EEG windows synchronize all
+                     their "slave" windows with them. Simply means you can move
+                     the cursor, and see the result accordingly!
+                 
    
+             
  • 
+                 
    
+                     
+                          
+                         Average
+                      the values of the EEG if the 
+                         time
+                         cursor
+                      spreads across multiple time frames, then show the result:
+                 
    
+                 
    
+                     
+                 
    
+             
  • 
+                 
    
+                     
+                          
+                     Display a sequence of time frames if the 
+                         time
+                         cursor
+                      spreads across multiple time frames.
+                 
    
+                 
    
+                     Usually, there are more than one sequence layout available,
+                     just click again to toggle through all possibilities (the
+                     number of frames is controlled here):
+                 
    
+                 
    
+                     
+                 
    
+             
  • 
+                 
    
+                     
+                          
+                     Run an animation if the time cursor
+                     spreads across multiple time frames. Click again to stop
+                     or restart the animation (speed is controlled here):
+                 
    
+                 
    
+                     
+                 
    
+             
  • 
+                 
    
+                     
+                          
+                     In case of sequence or animation, 
+                         reduce the number of
+                         frames, or the speed
+                     .
+                 
    
+             
  • 
+                 
    
+                     
+                          
+                     In case of sequence or animation, 
+                         increase the number of
+                         frames, or the speed
+                     .
+                 
    
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+     

  
 
\ No newline at end of file
diff --git a/docs/ReferenceGuide/index.html b/docs/ReferenceGuide/index.html
index 41f9f064..90206814 100644
--- a/docs/ReferenceGuide/index.html
+++ b/docs/ReferenceGuide/index.html
@@ -8,127 +8,145 @@
 }
 
  
- 
-     
Cartool EEG Software
Reference Guide

-  

-   General Concepts

-  

-   Files and Views

-   Linking Files Together

-   Slave Windows
-  

-  

-   Displaying

-  

-  
-   
-   
-    
-     
-     
-     
-    
-    
-    
-     
-     
-     
-    
-    

-      

-       General Commands for all Windows
-      

-     		
-     

-      

-       EEG Display
Frequency 
-	   Display

-	   Segments Display

-	   Scalp & Intracranial Potentials Display
-	  

-     		
-      

-       MRIs and Volumes Display

-	   Inverse Solutions Display

-	   Using ROIs
-	  

-     

-    
-  

-   Processing, from Dialogs

-  

-  
-   
-   
-    
-     
-     
-    
-   
-    
-     
-       
-     
-		
-    
-    

-      

-       All the processing of Cartool
-      

-     		
-     

-	  

-       Reprocess / Export Tracks

-	   File Calculator

-	   Generate Markers from Tracks
-	  

-      

-       Computing ERPs and Averaging Tracks Files

-	   Tracks Interpolation

-	   Frequency Analysis
-	  

-      

-       Segmentation of EEG Files into Micro-States

-	   Back-Fitting Template Maps
-	  

-      

-       Creating & Using ROIs

-	   Statistics
-	  

-     		
-      

-       MRIs Preprocessing
MRI Coregistration to current MRI
MRIs 
-	   Skull Stripping

-	   Talairach Coordinates Conversion

-	   Creating a Template Electrodes Coordinates
-	  

-      

-       Coregistering Electrodes to 
-	   MRI
-	  

-      

-       Creating Inverse Solution Matrices

-	   Computing Results of Inverse Solution

-	   Results of Inverse Solution to Volumes
-	  

-     

-    
-  

-   Processing, from Command-Line

-  

-   Appendixes

-  

-   A. Problems Resolution

-   B. Cartool Slang & Various Formulas

-   C. Cartool File Formats

-   D. Files Handled by Cartool

-   E. Cartool Options

-  

-    

-  

-   All content written by Denis Brunet, © University of Geneva, Switzerland.

-   See the specific license for the documentation.
-   

-   
+ 
+
+     

+
+         
Cartool EEG Software
Reference Guide

+         

+             General Concepts
+         

+         

+             Files and Views

+             Linking Files Together

+             Slave Windows
+         

+         

+             Displaying
+         

+         

+
+             
+
+                 
+                     
+
+                     
+                 
+
+                 
+                     
+
+                     
+                 
+             

+                         

+                             General Commands for all Windows
+                         

+                     		
+                     

+                         

+                             EEG Display

+                                 Frequency
+                                 Display
+                             

+                             Segments Display

+                             Scalp & Intracranial Potentials Display
+                         

+                     		
+                         

+                             MRIs and Volumes Display

+                             Inverse Solutions Display

+                             Using ROIs
+                         

+                     

+         

+
+         

+             Processing, from Dialogs
+         

+         

+
+             
+
+                 
+                     
+                     
+                 
+
+                 
+                     
+
+                     
+
+                 
+             

+                         

+                             All the processing of Cartool
+                         

+                     		
+                     

+                         

+                             Reprocess / Export Tracks

+                             File Calculator

+                             Generate Markers from Tracks
+                         

+                         

+                             Computing ERPs or Averaging Tracks

+                             Tracks Interpolation

+                             Frequency Analysis
+                         

+                         

+                             Segmentation of EEG Files into Micro-States

+                             Back-Fitting Template Maps
+                         

+                         

+                             Creating & Using ROIs

+                             Statistics
+                         

+                     		
+                         

+                             MRIs Preprocessing
MRI Coregistration to current MRI
MRIs
+                             Skull Stripping

+                             Talairach Coordinates Conversion

+                             Creating a Template Electrodes Coordinates
+                         

+                         

+                             
+                                 Coregistering Electrodes to
+                                 MRI
+                             
+                         

+                         

+                             Creating Inverse Solution Matrices

+                             Computing Results of Inverse Solution

+                             Results of Inverse Solution to Volumes
+                         

+                     

+         

+
+         

+             Processing, from Command-Line
+         

+         

+             Appendixes
+         

+         

+             A. Problems Resolution

+             B. Cartool Slang & Various Formulas

+             C. Cartool File Formats

+             D. Files Handled by Cartool

+             E. Cartool Options
+         

+         

+              

+         

+         

+             All content written by Denis Brunet, © University of Geneva, Switzerland.

+             See the specific license for the documentation.
+         

+
+     

+ 
  
 
\ No newline at end of file
diff --git a/docs/ReferenceGuide/microstates-back-fitting-templates.html b/docs/ReferenceGuide/microstates-back-fitting-templates.html
index 063e68ec..8fbcf8c9 100644
--- a/docs/ReferenceGuide/microstates-back-fitting-templates.html
+++ b/docs/ReferenceGuide/microstates-back-fitting-templates.html
@@ -31,1621 +31,2130 @@
 }
   
  
- 
-  

-   Back-Fitting Template Maps

-  

-    

-  

-   The back-fitting is about taking the results from the
-   segmentation, and back-fitting them to the 
-   subjects to be able to extract variables for statistics.

-  

-    

-  

-   Fitting template maps back to 
-   subjects data

-  
-  

-   How to run the Fitting

-  
-  

-   Technical points & hints

-   Results
Fitting in the Inverse Solution space

-  

-   Fitting template maps back to subjects data

-  

-   Method used for the Fitting

-  

-   The idea here is to use the maps from the "best" 
-   segmentation of the Grand Means, and fit them back to the subject 
-   files, then apply some statistics on the results.

-  

-   Practically, this is simply this step 
-   from the K-Means segmentation 
-   process, simply assigning the map with the highest correlation 
-   at each time frame and for each file.

-  

-   How to run the Fitting

-  

-   Called from the Tools
-    | Fitting maps into EEG files menu, a dialog in 3 parts appears:

-  

-   Fitting Files Dialog

-  

-   

-    fitting files dialog

-   

-     

-   

-  

-   
-       
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-       
-     
-     
-       
-       
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-   

-      

-       (1) Templates to Fit

-      

-        

-      

-       Fit with Templates to File:

-      

-       Give the .ep file that 
-	   contains the templates, 
-       usually generated by the 
-	   Segmentation
-        process, that will be used for the fitting process.

-      

-       If you Drag & Drop a single .ep file, this will be 
-	   assumed as the 
-       template file.

-      

-       (2) Groups of Files to be Fit

-      

-        

-      

-        

-      

-       Read some important informations about the meaning
-        of Groups in the Fitting context.

-      

-       You can use the very convenient Drag & 
-       Drop feature here.

-      

-       Add New Group of Files

-      

-       Enter a new group of file(s).

-      

-       Remove Last Group

-      

-       Does what it says.

-      

-       Clear All Groups

-      

-       Clear out all the groups at once.

-      

-       Read Lists from File

-      

-       You can direclty retrieve the lists of groups previously (see below).

-      

-       See also Drag & Drop.

-      

-       Write Lists to File

-      

-       You can save the lists of current groups into a file, in case you 
-       want to re-use them (much recommended!).

-      

-       See the file formats available.

-      

-       Sort Files within Lists

-      

-       A strange behavior of Windows is to not respect the order of the 
-       files dropped in a window. To help cure this silly habit, you can 
-       sort all the file names of all the groups already entered.

-       New: Cartool will sort your files if you use 
-	   Drag & Drop...

-      

-       Number of Consecutive Groups within 
-	   Subjects:

-      

-       Default is to assume all dropped groups above are considered
-	   within-subjects. The 
-	   within-subjects number of groups is therefore equal to the total number 
-	   of groups.

-       If this is not the case, you can specify a smaller number of groups 
-	   within-subjects. F.ex. 8 groups of files, but first 4 are patients, last 
-	   4 controls, then you specify "4" as the number of consecutive 
-	   within-subjects.

-       A few remarks:
    
-		  
  • The number you set should be a integer divisor of 
-		  the total number of groups.
    • 
-		  
  •  You can set the number to 1 in case of 
-		  across-subjects design.
    • 
-		  
  • This value is very important to compute the proper 
-		  normalization factors of all the extracted variables.
    • 
-	  

-		   

-      

-       (3) Epochs to fit

-      

-       You can restrict the time interval to be fit with some given maps.

-      

-       From

-      

-       From time frame (included)

-      

-       To

-      

-       To time frame (included)

-      

-       with Maps

-      

-       A set of templates/maps for which the this epoch will be restricted to.

-        Let it empty, or set 
-       to *, to use all the maps.

-      

-       Add epoch

-      

-       Insert the specified epoch to the list.

-      

-       Don't forget to press on this button to enter the current values!

-      

-       If the list remains empty, the fitting process will be run on the 
-       whole files. Otherwise you can enter a serie of time ranges to 
-       restrict the fitting, but the epochs can not overlap.

-      

-       Remove epoch

-      

-       Remove last epoch from the list.

-      

-       (4) Output Options

-      

-        

-      

-       Output Base File Name

-      

-       Specify here a basis for all the file names that will be 
-       generated during the segmentation process.

-      

-       Output Segmentation Files:

-      

-       Saving a visual representation of the fitting as a segmentation file. If 
-	   you used different epochs, they will be all 
-	   merged together for display (they are forbidden to overlap).

-	  

-       Meaningful 
-       only if you run a competitive 
-       fitting process.

-	  

-       Files are located in the More subdirectory.

-      

-       Also see the .seg specification.

-      

-       Output Other Files:
Data per Cluster

-      

-       This option will save the clusters of maps. There will 
-	   be a file for each cluster, and for each subject, with all the data 
-	   assign to a given cluster.

-       Note that this will basically take the same amount of space as your input 
-	   data (minus the optional bad epochs).

-       This is a very handy option to later compute the localization of each 
-	   template map, for each subject.

-      

-       Temp Files:
Delete Preprocessed Files

-      

-       Subjects' data could be preprocessed, f.ex. with Spatial Filter and / or 
-	   GFP Normalization. With this option, these files are discarded after use 
-	   (the default).

-      

-       << Previous  |  Next >>

-      

-       Use these buttons to navigate through the previous and next dialogs 
-       (if any).

-      

-       See which current dialog you are in, and to which other dialogs you 
-       connect, in the tab-like part at the top of the dialog under 
-       the title.

-      	 

-      

-       Process

-      

-       Runs the fitting.

-      

-       This button remains disabled until all the parameter 
-       dialogs have received enough (and consistent) informations.

-      

-       Cancel

-      

-       Quit the dialog.

-      

-       Help

-      

-       Launch the Help to the right page (should be here...).

-  

-   Fitting Parameters Dialog

-  

-   fitting parameters dialog

-  

-    

-   
-	   
-     
-     
-       
-	   
-     
-     
-       
-    
-     
-     
-    
-       
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-       
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-   

-      

-       Presets:

-      

-       This is handy to quickly set the main parameters according to the 
-       most frequent uses, listed in the drop-down box.

-      

-       The most important parameters will be set, still some 
-       parameters have to be set manually! And, as usual, double 
-       check that all your settings make sense...

-      

-       (1) Data Preprocessing

-      

-       It is better to preprocess your files once and for all. In case this was 
-	   not the case, this is your last chance to apply these preprocessing 
-	   before the actual fitting.

-      

-       Spatial Filter, using XYZ file:

-      

-       Applying a Spatial Filter to the 
-	   data, to remove outliers and smooth out the 
-	   noise.

-       Be careful, avoid using this this filter more than 
-	   once! If your EEG preprocessing pipe-line already included 
-	   the Spatial Filter, you shouldn't use it here! Cartool tries to be 
-	   smart here, if your files contain the characters "Spatial" in their 
-	   names, it will automatically disable this option.

-      

-       Data level normalization

-      

-       This will rescale the data from each file by a given factor.

-      

-       None

-      

-       No rescaling.

-      

-       Mean Gfp

-      

-       According to the Number of Consecutive 
-	   Groups within Subjects parameter, the median GFP across all 
-	   within-subject files is computed and used for normalization. 
-	   This helps in reducing the inter-subjects variability.

-      

-       Excluding Bad Epochs:

-      

-       Select this option to skip some time periods from your data. 
-	   Data preprocessing is never perfect, and some parts of the data should 
-	   still be ignored.

-       Note that this step is done after the GFP Max, and before the resampling.

-      

-       Automatic

-      
Cartool has a bad epochs automatic detection (you might want to give it 
-	  a try from the EEG Window, under 
-	  Markers|Scanning Bad Markers menu).

-	  
This option is seen as a last chance before the clustering. It would 
-	  definitely be better to run the detection before, then visually 
-	  assess the bad epochs, then only run the clustering.

-		   

-      

-       At Markers

-      

-       Give the marker names of the bad epochs to be ignored.

-       Either somebody did put some markers manually to isolate the bad epochs, 
-	   or have already run the automatic bad epochs detection.

-      

-       (2) Labeling Parameters

-      

-        

-      

-       Data Type:

-      

-        

-      

-       Only Positive

-      

-       Data consist of positive only, scalar data. This could be 
-       spikes from neuron recordings, or the Results of Inverse Solution, f.ex.

-      

-       This will logically turn off the Polarity & References options.

-      

-       See this point on 
-       positive data and also this point.

-      

-       Signed

-      

-       Signed scalar values, like, you know, EEG.

-      

-       Vectorial

-      

-       Used on Inverse Solution 
-        .ris data files, 
-       when the results are vectors for each solution points.

-      

-       See this point about fitting in the Inverse 
-       Solution space.

-      

-       Data reference

-      

-        

-      

-       No Reference

-      

-       Data are used as they come from files, no changes occur.

-      

-       Average Reference

-      

-       Data are average reference-d.

-      

-       Maps / Patterns Polarity:

-      

-        

-      

-       Ignore

-      

-       Polarity of maps does not matter, so ignore it. Inverted maps are 
-       considered the same (same underlying generators, but with reversed polarity).

-      

-       Used for spontaneous EEG recordings.

-      

-       Account

-      

-       Polarity of maps matter, that is, inverted maps are indeed considered 
-       as different.

-      

-       Used for ERPs.

-      

-       To avoid missing values:
Use a Non-Competitive Fitting

-      

-       When off, all the maps compete with each others to be 
-       elected as the best fitting one for a given time frame. As only one 
-       map can win, the labeling is therefore a competitive process. This is 
-       the default.

-      

-       When on, it gives each map an exclusive access to the data, 
-       the labeling is therefore run on the whole file with a single map 
-       at a time. The process is repeated for each map. This is useful 
-       to produce variables with non-missing values for later statistics.

-      

-       Labeling at Low Correlations:
No Labeling if Below

-      

-       If selected, you can specify a minimum correlation threshold 
-	   for data points to be assigned to a given cluster.

-       Default correlation threshold is set to 50%, which is 
-	   quite conservative.

-       See this outliers rejection paragraph.

-      

-       (3) Temporal Postprocessing

-      

-        

-      

-       Segments Temporal Smoothing

-      

-       Redo the labeling, but with a temporal
-        smoothing factor.

-      

-       Window Half Size:

-      

-       The temporal smoothing operates with a sliding window, which you 
-       specify here the half size (in time frames). The actual window size 
-       is therefore ( 2 x W + 1 ).

-      

-       Strength (Besag Factor):

-      

-       Strength  
-       of the smoothing, actually the Besag factor from the article on the 
-       segmentation process.

-      

-       Rejecting Small Segments

-      

-       Deletes short segments, and fuse them with their 2 respective neighbors.

-      

-       Shorter than or equal to:

-      

-       Size below which a segment is removed.

-      

-       << Previous  |  Next >>

-      

-       Use these buttons to navigate through the previous and next dialogs 
-       (if any).

-      

-       See which current dialog you are in, and to which other dialogs you 
-       connect, in the tab-like part at the top of the dialog under 
-       the title.

-      	 

-      

-       Process

-      

-       Runs the 
-	   fitting.

-      

-       This button remains disabled until all the parameter 
-       dialogs have received enough (and consistent) informations.

-      

-       Cancel

-      

-       Quit the dialog.

-      

-       Help

-      

-       Launch the Help to the right page (should be here...).

-  

-   Fitting Results Dialog

-  

-   fitting parameters dialog

-  

-    

-   
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-   

-      

-       (1) Variables to Extract

-      

-       See here all the variables that 
-	   can be computed, for each subject and for 
-       each template map.

-	  

-       Note that you can be more selective than taking all variables (though it 
-	   doesn't hurt), according to your paradigm, some variables might not make 
-	   sense at all!

-	  

-       Also some of them will be unavailable in case of
-	   non-competitive fitting.

-      

-       See this note about the format of the 
-       array of results.

-      

-       All On
All Off

-				
-      

-       What is says, turns on / off all variables at once.

-      

-       Data Layout in Worksheet Files:

-      

-       You currently have 2 (non-exclusive) ways of outputting the 
-	   multi-dimensional resulting data.

-      

-       Lines As Samples

-      

-       This is a multiplexed format that can 
-	   be read by Cartool, Statistica, Excel. etc...

-       Each line correspond to an input file, then all columns (a lot) 
-	   will contain the variables.

-      

-       Columns As Factors

-      

-       This is an indexed array that can 
-	   be read by R.

-       There are some columns that hold the indexes, then the other columns that 
-	   hold the factors themselves.

-      

-       Splitting Results into Files

-      

-       You can also refine how many files to write with these 2 independent 
-	   options.

-      

-       Force 1 File per Group

-      

-       1 output file for each group of input file. This is now 
-	   the default, as it is more handy to manipulate for statistics.

-       When option is off, it will pack all
-	   within subjects groups into a 
-	   single file.

-       This can be combined with splitting the variables option below.

-      

-       Force 1 File per Variable

-      

-       1 output file for each computed variable. Not recommended, as it may 
-	   create a lot of files.

-       When option if off, all variables are saved into the same file.

-       This can be combined with splitting the group option above.

-      

-       Force
-       Short Variable Names

-      

-       Choose between long (and more explicit) or short (cryptic) variable names.

-      

-       See this note and this one about the format
-        of the array of results.

-      

-       (2) Markov Chains

-      

-        

-      

-       Joints States Probabilites

-      

-       Used to study the transitions from between states.

-       See this paragraph.

-      

-       Transition Matrices

-      

-       Used to study the transitions from between states.

-       See this paragraph.

-      

-       Number of Transitions ahead:

-      

-       Number of forward transitions to take into account.

-       This only compute the probabilities from the current state to the
-	    nth-next 
-	   state, and not the order of the Markov Chains 
-	   (all combinations of nth 
-	   to previous states, to current one).

-      

-       (3) Resting States

-      

-       These options apply to spontaneous type of data only.

-      

-       Save Durations Histograms

-      

-       What it says.

-       There will be 2 histograms per map for each subject, one with 
-	   linear time scale, and one with 
-	   log time scale. 
-	   Then another 2 histograms per map, but for all subjects together.

-      

-       
-	   Save Segments Frequency

-      

-       This option will create new files, with the number of templates as number 
-	   of tracks, and each input file original time scale. The tracks will be 
-	   filled with a raised cosine bump at each segment location, 
-	   so that repeating segments will appear as a sine wave, which frequency is 
-	   related to the duration of each segment.

-       Any type of frequency analysis can 
-	   then be applied on these files.

-       These files are located in the Segments 
-	   Frequency subdirectory.

-		   

-      

-       
-	   Save Correlations of Data and 
-	   Maps

-      

-       Saving for each input file the correlation with each template map.

-	  

-       F.ex. if you give 10 maps to be fit, the output will have the number 
-	   of time frames of the original files, and 10 tracks showing the 
-	   correlation of each map for the current time frame.

-	  

-       These files are located in the Correlations subdirectory.

-		

-      

-       << Previous  |  Next >>

-      

-       Use these buttons to navigate through the previous and next dialogs 
-       (if any).

-      

-       See which current dialog you are in, and to which other dialogs you 
-       connect, in the tab-like part at the top of the dialog under 
-       the title.

-      	 

-      

-       Process

-      

-       Runs the 
-	   fitting.

-      

-       This button remains disabled until all the parameter 
-       dialogs have received enough (and consistent) informations.

-      

-       Cancel

-      

-       Quit the dialog.

-      

-       Help

-      

-       Launch the Help to the right page (should be here...).

-  

-   Fitting - Technical points & hints

-  

-   Groups of Files in the Fitting

-  

-   Groups of files can be of the same size or be of different sizes, depending 
-   on you experiment and the type of statistics you are going to use.

-  

-   If your groups have different size, meaning the number of subjects is not the 
-   same across groupsn, then Cartool will force set the
-   within-subjects parameter to 1.

-  

-    

-  

-   The fitting is optimized to have the lowest memory footprint 
-   and highest computation speed, and will load only the 
-   absolute necessary files into memory at nay given time. This allows you to have 
-   any arbitrarily big groups of files to fit, even if they are original recording 
-   (which can be large by themselves).

-  

-   Number of consecutive within-subjects 
-   groups

-  

-   ('Group' here means a group of file you dropped in, and shown as such in the 
-   list box)

-  

-   A set of groups can (and actually should be) grouped 
-   together if they were part of a within-subjects paradigm. 
-   Practically, this means that all the files from these groups were recorded 
-   from identical subjects, row-wise speaking. It also implies that these groups 
-   have the same number of files. F.ex. a paired experiment will be grouped by 
-   2.

-  

-   Once Cartool knows how many af these groups have to to joined together, it 
-   will compute the normalization part (denominator part of the 
-   equations) of the GEV  and
-   GFP normalization with all subject's files together. Again 
-   for a paired experiment, the 2 files of a subject are used to compute the sum 
-   of the squares of map, and the sum of GFP, which are therefor used to compute 
-   the GEV and normalize by GFP respectively.

-  

-   Failing to define properly the parameter will lead to a wrong normalization 
-   of the data. If on the file has one more big component, it will relatively 
-   make the other components looking artificially weaker, and hence could 
-   produce erroneous positive tests on these components with their apparent 
-   intensities difference.

-  

-    

-  

-   Cartool will suggest using the biggest denominator across all current groups' 
-   sizes for this parameter. But you should check this is correct according to 
-   your experiment design. With our example of a paired experiment, if you 
-   dropped 4 files, and they are grouped by 2, then Cartool will run the fitting 
-   on the groups 1 and 2 together, and then independently on the groups 3 and 4 
-   together.

-  

-   Variable names

-  

-   The full variable names can have two different formats, namely the 
-   short and the long versions. Choose the version according to the 
-   program you are going to send the results to, though I think the long 
-   version is clearer (Cartool can read both, however).

-  

-   Variable names always consist of 3 parts joined together by a 
-   "_" (underscore):

-  
    
-   
  • 
-   
    
-    The group index
    
-    
  • The map / cluster index
    
-    
  • The variable computed
    
-   

-  

-   So f.ex.:

-  
    
-   
  • 
-   
    
-    Long: Group1_Map1_NumTF, Group1_Map2_NumTF, Group1_Map1_MaxGfp...
    
-    
  • Short: G1_M1_N, G1_M2_N, G1_M1_X...
    
-   

-  

-    

-  

-   The variables that can be computed are currently the 
-   following. They can be further processed with Cartool
-    Statistics, or the tools of your choice:

-  

-    

-  

-   

-    
-        
-      
-      
-      
-      
-        
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-        
-      
-      
-      
-      
-        
-     
-      
-      
-      
-      
-     
-        
-      
-      
-      
-      
-        
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-        
-      
-      
-      
-      
-        
-		
-      
-      
-      
-      
-        
-		
-      
-      
-      
-      
-        
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-    

-       Variable
-       Meaning
-       Unit
-       Missing Value

-       

-        First Onset

-       

-        The first time frame of appearance, for a given map and a 
-        given file.

-		 		
-       

-        Time frame

-         		
-       

-        -1

-       

-        Last Offset

-       

-        The last time frame of appearance, for a given map and a given 
-		file.

-		 		
-       

-        Time frame

-         		
-       

-        -1

-       

-        Number of TFs

-       

-        Total number of time frames of appearance, for a given map and 
-        a given file.

-		 		
-       

-        Time frame

-         		
-       

-        0

-       

-        Mean Correlation

-       

-        Mean correlation, for a given map and a given file.

-       

-        No unit
range in [-1..1]

-       	 		
-       

-        -1

-       	 

-       

-        GEV

-       

-        Global Explain Variance, 
-        contribution splitted for each map, for a given file.

-		 		
-       

-        No unit
range in [-1..1]

-         		
-       

-        0

-         

-       

-        TF of Centroid

-       

-        The GFP-weighted mean time frame position, for a given map and a 
-		given file.

-					
-       

-        Time frame

-       	 		
-       

-        -1

-       	 

-       

-        Best Correlation

-       

-        Highest Correlation 
-        value encountered, for a given map and a given file...

-         		
-       

-        No unit
range in [-1..1]

-         		
-       

-        -1

-         

-       

-        TF of Best Correlation

-       

-        ...and its position...

-		 		
-       

-        Time frame

-         		
-       

-        -1

-         

-       

-        Gfp of TF of Best Correlation

-       

-        ...and the Gfp value at that position.

-		 		
-       

-        Identical to input data, usually [milli-volts]

-         		
-       

-        -1

-         

-       

-        Max Gfp

-       

-        The max Gfp over the segment fit by a given map...

-       	 		
-       

-        Identical to input data, usually [milli-volts]

-       	 		
-       

-        0

-       	 

-       

-        TF of Max Gfp

-       

-        ...and its position.

-					
-       

-        Time frame

-       	 		
-       

-        -1

-       	 

-       

-        Mean Gfp

-       

-        The mean G over the segment fit by a given map.

-       	 		
-       

-        Identical to input data, usually [milli-volts]

-       	 		
-       

-        0

-       	 

-       

-        Mean Duration

-       

-        Mean length of segments.

-		 		
-       

-        Millisecond
(older version was in time frame)

-         		
-       

-        0

-         

-       

-        Time Coverage

-       

-        Percentage in time coverage, i.e. the number of time 
-		frames for each template divided by the total number of labeled time frames

-		 		
-       

-        Percentage [0..100]
(older version was in range [0..1])

-		 		
-       

-        0

-         

-       

-        Segment Count Density
Occurences per second 
-		in some papers

-       

-        Number of segments divided by the total labeled duration.

-		 		
-       

-        Count per second, not a frequency!
(older 
-		version was in 
-		count per time frame)

-		 		
-       

-        0

-         

-   

-  

-   Markov Chains

-  

-   The aim is to compute statistics on the transitions probabilities, to show
-   some kind of syntax in the sequences of micro-states. These
-   transitions are computed from the segments (all consecutive 
-   time points of identical label stands for 1 state), and not on the 
-   time frame level.

-  

-   Cartool will output various Worksheets .csv files 
-   which contain, for each subject, either the expected probability from 
-   going to segment A to segment B, or the observed probability 
-   from the data. Then we can compare the two statistically. The 
-   expected probabilities are theoretical values based on the count of segments 
-   for each template map. While the observed probabilities come from actually 
-   scanning the transitions from each and every segment to all the others.

-  

-    

-  

-   Cartool will output 2 types of probabilities, the difference between the two 
-   being how the probabilities are normalized:

-  
    
-	  
  • Markov probabilities: the sum 
-	  of all probabilities for each line of the transition matrix is equal to 1.
    
-	  F.ex. showing below the observed values (6 maps + Unlabeled):
    
-	  
    • 
-	  
  • Joint States Probabilities: the 
-	  sum of all probabilities of the whole transition matrix is equal to 1.
    
-	  F.ex. showing below the observed values (6 maps + Unlabeled):
    
-	  
    • 
-  

-  
 

-  

-   Note 1: In case a minimum correlation 
-   threshold has been set, we end up with an additional "state", the one 
-   with undefined labeling. Undefined data points are the one which don't 
-   correlate well enough to any template maps. It is a sort of "garbage" 
-   cluster, so to speak. It behaves like a regular cluster for all the 
-   transition probabilities computation, though.

-  

-   Note 2: The number of transitions ahead is which segment is 
-   considered the one to compute the transition to. Default is 1, which means 
-   the next segment. If you set to a higher value, like 2, the second-next 
-   segment will be used. This is not the traditional Markov order.

-  

-   Duration histograms

-  

-   Two files per subject are outputed, one with linear and one with log time 
-   scale: 

-  

-   

-  

-   

-  

-   You can run statistics on the duration histograms.

-  

-   Segments frequency

-  

-   This option will create a new time line for each map (top picture), where each 
-   segment (bottom picture) is replaced by a raised cosine bump. Here you can 
-   focus at map 1 as a good example:

-  

-   

-  

-   

-  

-   This can be used for frequency analysis.

-  

-   Correlation output

-  

-   Across time correlation shows the correlation between each template 
-   map and every data point. Values are within the [0..1] range:

-  

-   

-  

-    

-  

-   Once we have these time lines, we can again correlate them. This will show
-   how each correlation time course looks similar to the other ones 
-   (which is not to be confused with the correlation between maps):

-  

-   

-  

-   Fitting - Results

-  
    
-   
  • 
-   
    
-    A .vrb verbose file, 
-	containing all the parameters being used, plus the GFP normalization factors 
-	computed 
-	per file(s), if the option was selected.
    
-	  
  • 
-      
    
-      A copy of the input templates .ep 
-	  and its corresponding .seg 
-	  files.
    
-	  
  • 
-      
    
-      Then for each group of files:

    
-      
      
-		  
    • 
-		  
      In the root directory, 1 or n .csv files,
      
-		      
-		  <basefilename>.Group<#>.LinesAsSamples.csv       and / or
      
-		      
-		  <basefilename>.Group<#>.FactorsAsColumns.csv
      each 
-		  file containing all the output variables, arranged 
-		  in different layouts to match your 
-		  analysis tools.
      
-		  
    • 
-		  
      In the root directory,
          <basefilename>.Group<#>.seg 
-    	  
      is the labeling file of all subjects together (only in case of 
-		  non-competitive fitting BTW)
      
-		  
    • 
-		  
      In the Segmentations directory,
          <basefilename>.Group<#>.Subj<#>      .seg       
-		  
      contain labeling split by subject.
      
-		  
    • 
-		  
      In the Data Clusters directory,
          <basefilename>.Subject<#>.<original 
-		  file name>.Cluster<#>.*.sef
      contain all the maps 
-		  assign to a given cluster.
      
-		  
    • 
-		  
      In the Markov Chains directory, and in case of 
-		  Markov output,
      
-		  
        
-			  
      • 
-			  
        <basefilename>.Group<#>.MarkovChains<#>.*.csv 
-			  files .
        Each 
-			  file contains the probabilities of  transitions (templatei → 
-			  templatej), 
-			  with 1 file for each step ranging from 1 to the maximum set in the 
-			  parameters.
        The format of the .csv 
-			  follows these options.
        
-			  
      • 
-			  
        <basefilename>.Group<#>.MarkovChains.freq 
-			  files.
        These are the same data as the above .csv 
-			  files, but all transitions are stored (trick) into a .freq file. In this case, the "frequency" dimension 
-			  will hold the transitions dimension, the "time" dimension will 
-			  will hold the subjects index dimension.
        
-		  
      
-		  
    • 
-		  
      In the Histograms Duration directory,
         
-		  <basefilename>.Subject<#>.HistoDuration.Lin.sef   
-		  and
          <basefilename>.Subject<#>.HistoDuration.Log.sef      
-		  
      contain the histograms of segments' durations.
      
-		  
    • 
-		  
      In the Segments Frequency directory, and 
-		  in case of segments frequency 
-		  output, 
          <basefilename>.Group<#>.Subj<#>.SegFreq.sef
      files 
-		  hold the segments coded as bumps, with 1 track per template, 
-		  reflecting the frequency of the fit templates.
      
-		  
    • 
-		  
      In the Correlations directory, and in case of
-		  correlation output,
          <basefilename>.Group<#>.Subj<#>.CorrDataTempl      .sef
      
-		      <basefilename>.Group<#>.Subj<#>.CorrTempl.sef
      
-		  files 
-		  hold the correlations of the data with each template, and the 
-		  correlation of the correlations.
      
-	  
    
-   

-  

-    

-  

-   Also see the technical points, and 
-   especially the GEV remarks.

-  

-   Format of the .csv results

-  

-   As for today, there are 2 output arrays, each with a 
-   different formatting and targetting different packages. They however
-   contain exactly the same data, this is just a matter of 
-   formatting the 4D (number of groups x number of subjects x
-   number of segments x number of variables) dataset...

-  

-    

-  

-   The .LinesAsSamples.csv file

-  

-   Each line correspond to a subject, so the number of subjects 
-   is equal to the total number of lines - 1 (the header line).

-  

-   This is the format used by Cartool and
-   Statistica for its statistical analysis.

-  

-   With this format, lines end up to be huge, and sometimes will fail to be read 
-   by Excel, though Cartool and other analysis packages will have no 
-   problems reading them.

-  

-    

-  

-   The format is the following:

-  
    
-   
  • 
-   
    
-    First line is a header which lists all the 
-	mutliplexed variables' name. First variable name is always 
-	Subject, then there are many variables with format of the like 
-	Group*_Map*_VariableName.
  • 
-      
    
-      Next lines hold the data themselves, with 1 row/line per 
-	  subject (so each line can be quite long):
      
-		  
    • 
-		  
      Data are mulitplexed by Group, then Map, then Variable, in this 
-		  order from outer to inner variable loop.
      F.ex. you'll find first 
-		  all the variables of Group1, Map1, then all the variables of Group1, 
-		  Map2, etc.. for all maps, then all the variables of Group2, Map1, then 
-		  all the variables of Group2, Map2, etc...
    • 
-		  
      Data are written either in integer or floatting point, according to 
-		  their actual types (integer for counts f.ex., floatting point for GEV, 
-		  Gfp etc...)
    
-   

-  

-    

-  

-   Here is an example of the actual ordering (the formatting 
-   itself is skipped for clarity), for 3 files, 2 groups, 2 maps, and 2 
-   variables (NumTF and Gfp). The names in italic indicate 
-   some actual data:
File1	Group1_Map1_NumTF  Group1_Map1_MaxGfp  Group1_Map2_NumTF  Group1_Map2_MaxGfp  Group2_Map1_NumTF  Group2_Map1_MaxGfp  Group2_Map2_NumTF  Group2_Map2_MaxGfp
File2	Group1_Map1_NumTF  Group1_Map1_MaxGfp  Group1_Map2_NumTF  Group1_Map2_MaxGfp  Group2_Map1_NumTF  Group2_Map1_MaxGfp  Group2_Map2_NumTF  Group2_Map2_MaxGfp
File3	Group1_Map1_NumTF  Group1_Map1_MaxGfp  Group1_Map2_NumTF  Group1_Map2_MaxGfp  Group2_Map1_NumTF  Group2_Map1_MaxGfp  Group2_Map2_NumTF  Group2_Map2_MaxGfp

-  
 

-  

-   The .ColumnsAsFactors.csv file

-  

-   Each column is a factor / variable.

-  

-   This is the format used by R.

-  

-   With this format, and contrary to the Lines As Samples format above, lines 
-   are hopefully much shorter. The counterpart is that the number of lines is 
-   much higher, and you have to make sure that all combinations of Files, Groups 
-   and Maps indexes exist (like the indexes of a 3D array).

-  

-    

-  

-   The format is the following:

-  
    
-   
  • 
-   
    
-    First line is a header which lists all the 
-	variables' name. First variables names are always Subject,
-	Group and Map, then followed by all the
-	variables names.
  • 
-      
    
-      Next lines hold the data themselves:
      
-		  
    • 
-		  
      The first 3 values hold the file name, group 
-		  index, and map index, all in text.
      F.ex.    File1    
-		  Group2    Map5
    • 
-		  
      Next are all the variables values, in the order listed 
-		  from the header line.
    • 
-		  
      Data are not necessarily ordered, though they are currently written 
-		  first by Group, then by Map, then by Variable.
    
-   

-  

-    

-  

-   Here is an example of the actual ordering (the formatting 
-   itself is skipped for clarity), for 3 files, 2 groups, 2 maps, and 2 
-   variables (NumTF and Gfp). The names in italic indicate 
-   some actual data:

-  
File1	Group1	Map1	Group1_Map1_NumTF  Group1_Map1_MaxGfp
+ 
+     

+         

+             Back-Fitting Template Maps
+         

+         

+              
+         

+         

+             The back-fitting is about taking the results from the
+             segmentation, and back-fitting them to the
+             subjects to be able to extract variables for statistics.
+         

+         

+              
+         

+         

+             
+                 Fitting template maps back to
+                 subjects data
+             
+         

+         
+         

+             How to run the Fitting
+         

+         
+         

+             Technical points & hints

+             Results
Fitting in the Inverse Solution space
+         

+         

+             Fitting template maps back to subjects data
+         

+         

+             Method used for the Fitting
+         

+         

+             The idea here is to use the maps from the "best"
+             segmentation of the Grand Means, and fit them back to the subject
+             files, then apply some statistics on the results.
+         

+         

+             Practically, this is simply this step
+             from the K-Means segmentation
+             process, simply assigning the map with the highest correlation
+             at each time frame and for each file.
+         

+         

+             How to run the Fitting
+         

+         

+             Called from the 
+                 
+                     Tools
+                     | Fitting maps into EEG files
+                 
+              menu, a dialog in 3 parts appears:
+         

+         

+             Fitting Files Dialog
+         

+         

+             

+                 fitting files dialog
+             

+             

+                  
+             

+         

+         

+             
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+             

+                         

+                             (1) Templates to Fit
+                     

+                         

+                              
+                     

+                         

+                             Fit with Templates to File:
+                     

+                         

+                             Give the .ep file that
+                             contains the templates,
+                             usually generated by the
+                             
+                                 Segmentation
+                                 process
+                             , that will be used for the fitting process.
+                         

+                         

+                             If you Drag & Drop a single .ep file, this will be
+                             assumed as the
+                             template file.
+                     

+                         

+                             (2) Groups of Files to be Fit
+                     

+                         

+                              
+                     

+                         

+                              
+                     

+                         

+                             Read some important informations about the 
+                                 meaning
+                                 of Groups
+                              in the Fitting context.
+                         

+                         

+                             You can use the very convenient 
+                                 Drag &
+                                 Drop feature
+                              here.
+                     

+                         

+                             Add New Group of Files
+                     

+                         

+                             Enter a new group of file(s).
+                     

+                         

+                             Remove Last Group
+                     

+                         

+                             Does what it says.
+                     

+                         

+                             Clear All Groups
+                     

+                         

+                             Clear out all the groups at once.
+                     

+                         

+                             Read Lists from File
+                     

+                         

+                             You can direclty retrieve the lists of groups previously (see below).
+                         

+                         

+                             See also Drag & Drop.
+                     

+                         

+                             Write Lists to File
+                     

+                         

+                             You can save the lists of current groups into a file, in case you
+                             want to re-use them (much recommended!).
+                         

+                         

+                             See the file formats available.
+                     

+                         

+                             Sort Files within Lists
+                     

+                         

+                             A strange behavior of Windows is to not respect the order of the
+                             files dropped in a window. To help cure this silly habit, you can
+                             sort all the file names of all the groups already entered.
+                         

+                             New: Cartool will sort your files if you use 
+                                 Drag & Drop
+                             ...
+                     

+                         

+                             
+                                 Number of Consecutive Groups within
+                                 Subjects:
+                             
+                     

+                         

+                             Default is to assume 
+                                 all dropped groups above are considered
+                                 within-subjects
+                             . The
+                             within-subjects number of groups is therefore equal to the total number
+                             of groups.
+                         

+                             If this is not the case, you can specify a smaller number of groups
+                             within-subjects. F.ex. 8 groups of files, but first 4 are patients, last
+                             4 controls, then you specify "4" as the number of consecutive
+                             within-subjects.
+                         

+                             A few remarks:
    
+                                 
  • 
+                                     The number you set should be a integer divisor of
+                                     the total number of groups.
+                                 
    • 
+                                 
  • 
+                                      You can set the number to 1 in case of
+                                     across-subjects design.
+                                 
    • 
+                                 
  • 
+                                     This value is very important to compute the proper
+                                     normalization factors of all the extracted variables.
+                                 
    • 
+                             

+                     

+                         

+                             (3) Epochs to fit
+                     

+                         

+                             You can restrict the time interval to be fit with some given maps.
+                     

+                         

+                             From
+                     

+                         

+                             From time frame (included)
+                     

+                         

+                             To
+                     

+                         

+                             To time frame (included)
+                     

+                         

+                             with Maps
+                     

+                         

+                             A set of templates/maps for which the this epoch will be restricted to.
+                         

+                              Let it empty, or set
+                             to *, to use all the maps.
+                     

+                         

+                             Add epoch
+                     

+                         

+                             Insert the specified epoch to the list.
+                         

+                         

+                             Don't forget to press on this button to enter the current values!
+                         

+                         

+                             If the list remains empty, the fitting process will be run on the
+                             whole files. Otherwise you can enter a serie of time ranges to
+                             restrict the fitting, but the epochs can not overlap.
+                     

+                         

+                             Remove epoch
+                     

+                         

+                             Remove last epoch from the list.
+                     

+                         

+                             (4) Output Options
+                     

+                         

+                              
+                     

+                         

+                             Output Base File Name
+                     

+                         

+                             Specify here a basis for all the file names that will be
+                             generated during the segmentation process.
+                     

+                         

+                             Output Segmentation Files:
+                     

+                         

+                             Saving a visual representation of the fitting as a segmentation file. If
+                             you used different epochs, they will be all
+                             merged together for display (they are forbidden to overlap).
+                         

+                         

+                             Meaningful
+                             only if you run a competitive
+                             fitting process.
+                         

+                         

+                             Files are located in the More subdirectory.
+                         

+                         

+                             Also see the .seg specification.
+                     

+                         

+                             Output Other Files:
Data per Cluster
+                     

+                         

+                             This option will save the clusters of maps. There will
+                             be a file for each cluster, and for each subject, with all the data
+                             assign to a given cluster.
+                         

+                             Note that this will basically take the same amount of space as your input
+                             data (minus the optional bad epochs).
+                         

+                             This is a very handy option to later compute the localization of each
+                             template map, for each subject.
+                     

+                         

+                             Temp Files:
Delete Preprocessed Files
+                     

+                         

+                             Subjects' data could be preprocessed, f.ex. with Spatial Filter and / or
+                             GFP Normalization. With this option, these files are discarded after use
+                             (the default).
+                     

+                         

+                             << Previous  |  Next >>
+                     

+                         

+                             Use these buttons to navigate through the previous and next dialogs
+                             (if any).
+                         

+                         

+                             See which current dialog you are in, and to which other dialogs you
+                             connect, in the tab-like part at the top of the dialog under
+                             the title.
+                         

+                     

+                         

+                             Process
+                     

+                         

+                             Runs the fitting.
+                         

+                         

+                             This button remains 
+                                 disabled until all the parameter
+                                 dialogs have received enough (and consistent) informations
+                             .
+                     

+                         

+                             Cancel
+                     

+                         

+                             Quit the dialog.
+                     

+                         

+                             Help
+                     

+                         

+                             Launch the Help to the right page (should be here...).
+                     

+         

+         

+             Fitting Parameters Dialog
+         

+         

+             fitting parameters dialog
+         

+         

+              
+         

+         
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+         

+                     

+                         Presets:
+                 

+                     

+                         This is handy to quickly set the main parameters according to the
+                         most frequent uses, listed in the drop-down box.
+                     

+                     

+                         The most important parameters will be set, still 
+                             
+                                 some
+                                 parameters have to be set manually!
+                             
+                          And, as usual, double
+                         check that all your settings make sense...
+                 

+                     

+                         (1) Data Preprocessing
+                 

+                     

+                         It is better to preprocess your files once and for all. In case this was
+                         not the case, this is your last chance to apply these preprocessing
+                         before the actual fitting.
+                 

+                     

+                         Spatial Filter, using XYZ file:
+                 

+                     

+                         Applying a Spatial Filter to the
+                         data, to remove outliers and 
+                             smooth out the
+                             noise
+                         .
+                     

+                         Be careful, avoid using this this filter more than
+                         once! 
+                             If your EEG preprocessing pipe-line already included
+                             the Spatial Filter, you shouldn't use it here!
+                          Cartool tries to be
+                         smart here, if your files contain the characters "Spatial" in their
+                         names, it will automatically disable this option.
+                 

+                     

+                         Data level normalization
+                 

+                     

+                         This will rescale the data from each file by a given factor.
+                 

+                     

+                         None
+                 

+                     

+                         No rescaling.
+                 

+                     

+                         Mean Gfp
+                 

+                     

+                         According to the 
+                             Number of Consecutive
+                             Groups within Subjects
+                          parameter, the 
+                             median GFP across all
+                             within-subject files
+                          is computed and used for normalization.
+                         This helps in reducing the inter-subjects variability.
+                 

+                     

+                         Excluding Bad Epochs:
+                 

+                     

+                         Select this option to skip some time periods from your data.
+                         Data preprocessing is never perfect, and some parts of the data should
+                         still be ignored.
+                     

+                         Note that this step is done after the GFP Max, and before the resampling.
+                 

+                     

+                         Automatic
+                 

+                     

+                         Cartool has a bad epochs automatic detection (you might want to give it
+                         a try from the EEG Window, under 
+                             Markers|Scanning Bad Markers
+                          menu).
+                     

+                     

+                         This option is seen as a last chance before the clustering. It would
+                         definitely be better to run the detection before, then visually
+                         assess the bad epochs, then only run the clustering.
+                     

+                 

+                     

+                         At Markers
+                 

+                     

+                         Give the marker names of the bad epochs to be ignored.
+                     

+                         Either somebody did put some markers manually to isolate the bad epochs,
+                         or have already run the automatic bad epochs detection.
+                 

+                     

+                         (2) Labeling Parameters
+                 

+                     

+                          
+                 

+                     

+                         Data Type:
+                 

+                     

+                          
+                 

+                     

+                         Only Positive
+                 

+                     

+                         Data consist of positive only, scalar data. This could be
+                         spikes from neuron recordings, or the Results of Inverse Solution, f.ex.
+                     

+                     

+                         This will logically turn off the Polarity & References options.
+                     

+                     

+                         See this 
+                             point on
+                             positive data
+                          and also this point.
+                 

+                     

+                         Signed
+                 

+                     

+                         Signed scalar values, like, you know, EEG.
+                 

+                     

+                         Vectorial
+                 

+                     

+                         Used on Inverse Solution 
+                         .ris data files,
+                         when the results are vectors for each solution points.
+                     

+                     

+                         See this point about 
+                             fitting in the Inverse
+                             Solution space
+                         .
+                 

+                     

+                         Data reference
+                 

+                     

+                          
+                 

+                     

+                         No Reference
+                 

+                     

+                         Data are used as they come from files, no changes occur.
+                 

+                     

+                         Average Reference
+                 

+                     

+                         Data are average reference-d.
+                 

+                     

+                         Maps / Patterns Polarity:
+                 

+                     

+                          
+                 

+                     

+                         Ignore
+                 

+                     

+                         Polarity of maps does not matter, so ignore it. Inverted maps are
+                         considered the same (same underlying generators, but with reversed polarity).
+                     

+                     

+                         Used for spontaneous EEG recordings.
+                 

+                     

+                         Account
+                 

+                     

+                         Polarity of maps matter, that is, inverted maps are indeed considered
+                         as different.
+                     

+                     

+                         Used for ERPs.
+                 

+                     

+                         To avoid missing values:
Use a Non-Competitive Fitting
+                 

+                     

+                         When off, all the maps compete with each others to be
+                         elected as the best fitting one for a given time frame. As only one
+                         map can win, the labeling is therefore a competitive process. This is
+                         the default.
+                     

+                     

+                         When on, it gives each map an exclusive access to the data,
+                         the labeling is therefore run on the 
+                             whole file with a single map
+                             at a time
+                         . The process is repeated for each map. This is useful
+                         to produce variables with non-missing values for later statistics.
+                 

+                     

+                         Labeling at Low Correlations:
No Labeling if Below
+                 

+                     

+                         If selected, you can specify a minimum correlation threshold
+                         for data points to be assigned to a given cluster.
+                     

+                         Default correlation threshold is set to 50%, which is
+                         quite conservative.
+                     

+                         See this outliers rejection paragraph.
+                 

+                     

+                         (3) Temporal Postprocessing
+                 

+                     

+                          
+                 

+                     

+                         Segments Temporal Smoothing
+                 

+                     

+                         Redo the labeling, but with a 
+                             temporal
+                             smoothing factor
+                         .
+                 

+                     

+                         Window Half Size:
+                 

+                     

+                         The temporal smoothing operates with a sliding window, which you
+                         specify here the half size (in time frames). The actual window size
+                         is therefore ( 2 x W + 1 ).
+                 

+                     

+                         Strength (Besag Factor):
+                 

+                     

+                         Strength 
+                         of the smoothing, actually the Besag factor from the article on the
+                         segmentation process.
+                 

+                     

+                         Rejecting Small Segments
+                 

+                     

+                         Deletes short segments, and fuse them with their 2 respective neighbors.
+                 

+                     

+                         Shorter than or equal to:
+                 

+                     

+                         Size below which a segment is removed.
+                 

+                     

+                         << Previous  |  Next >>
+                 

+                     

+                         Use these buttons to navigate through the previous and next dialogs
+                         (if any).
+                     

+                     

+                         See which current dialog you are in, and to which other dialogs you
+                         connect, in the tab-like part at the top of the dialog under
+                         the title.
+                     

+                 

+                     

+                         Process
+                 

+                     

+                         Runs the
+                         fitting.
+                     

+                     

+                         This button remains 
+                             disabled until all the parameter
+                             dialogs have received enough (and consistent) informations
+                         .
+                 

+                     

+                         Cancel
+                 

+                     

+                         Quit the dialog.
+                 

+                     

+                         Help
+                 

+                     

+                         Launch the Help to the right page (should be here...).
+                 

+         

+             Fitting Results Dialog
+         

+         

+             fitting parameters dialog
+         

+         

+              
+         

+         
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+         

+                     

+                         (1) Variables to Extract
+                 

+                     

+                         See here all the variables that
+                         can be computed, 
+                             for each subject and for
+                             each template map
+                         .
+                     

+                     

+                         Note that you can be more selective than taking all variables (though it
+                         doesn't hurt), according to your paradigm, some variables might not make
+                         sense at all!
+                     

+                     

+                         Also some of them will be unavailable in case of
+                         non-competitive fitting.
+                     

+                     

+                         See this note about the 
+                             format of the
+                             array of results
+                         .
+                 

+                     

+                         All On
All Off
+                     

+                 		
+                     

+                         What is says, turns on / off all variables at once.
+                 

+                     

+                         Data Layout in Worksheet Files:
+                 

+                     

+                         You currently have 2 (non-exclusive) ways of outputting the
+                         multi-dimensional resulting data.
+                 

+                     

+                         Lines As Samples
+                 

+                     

+                         This is a multiplexed format that can
+                         be read by Cartool, Statistica, Excel. etc...
+                     

+                         Each line correspond to an input file, then all columns (a lot)
+                         will contain the variables.
+                 

+                     

+                         Columns As Factors
+                 

+                     

+                         This is an indexed array that can
+                         be read by R.
+                     

+                         There are some columns that hold the indexes, then the other columns that
+                         hold the factors themselves.
+                 

+                     

+                         Splitting Results into Files
+                 

+                     

+                         You can also refine how many files to write with these 2 independent
+                         options.
+                 

+                     

+                         Force 1 File per Group
+                 

+                     

+                         1 output file for each group of input file. This is now
+                         the default, as it is more handy to manipulate for statistics.
+                     

+                         When option is off, it will pack all
+                         within subjects groups into a
+                         single file.
+                     

+                         This can be combined with splitting the variables option below.
+                 

+                     

+                         Force 1 File per Variable
+                 

+                     

+                         1 output file for each computed variable. Not recommended, as it may
+                         create a lot of files.
+                     

+                         When option if off, all variables are saved into the same file.
+                     

+                         This can be combined with splitting the group option above.
+                 

+                     

+                         Force
+                         Short Variable Names
+                 

+                     

+                         Choose between long (and more explicit) or short (cryptic) variable names.
+                     

+                     

+                         See this note and this one about the 
+                             format
+                             of the array of results
+                         .
+                 

+                     

+                         (2) Markov Chains
+                 

+                     

+                          
+                 

+                     

+                         Joints States Probabilites
+                 

+                     

+                         Used to study the transitions from between states.
+                     

+                         See this paragraph.
+                 

+                     

+                         Transition Matrices
+                 

+                     

+                         Used to study the transitions from between states.
+                     

+                         See this paragraph.
+                 

+                     

+                         Number of Transitions ahead:
+                 

+                     

+                         Number of forward transitions to take into account.
+                     

+                         This only compute the 
+                             probabilities from the current state to the
+                          nth
+                             -next
+                             state
+                         , and not the order of the Markov Chains
+                         (all combinations of nth
+                         to previous states, to current one).
+                 

+                     

+                         (3) Resting States
+                 

+                     

+                         These options apply to spontaneous type of data only.
+                 

+                     

+                         Save Durations Histograms
+                 

+                     

+                         What it says.
+                     

+                         There will be 2 histograms per map for each subject, one with 
+                             linear time scale
+                         , and one with
+                             log time scale
+                         .
+                         Then another 2 histograms per map, but for all subjects together.
+                 

+                     

+                         
+                         Save Segments Frequency
+                 

+                     

+                         This option will create new files, with the number of templates as number
+                         of tracks, and each input file original time scale. The tracks will be
+                         filled with a raised cosine bump at each segment location,
+                         so that repeating segments will appear as a sine wave, which frequency is
+                         related to the duration of each segment.
+                     

+                         Any type of frequency analysis can
+                         then be applied on these files.
+                     

+                         These files are located in the 
+                             
+                                 Segments
+                                 Frequency
+                             
+                          subdirectory.
+                     

+                 

+                     

+                         
+                         
+                             Save Correlations of Data and
+                             Maps
+                         
+                 

+                     

+                         Saving for each input file the correlation with each template map.
+                     

+                     

+                         F.ex. if you give 10 maps to be fit, the output will have the number
+                         of time frames of the original files, and 10 tracks showing the
+                         correlation of each map for the current time frame.
+                     

+                     

+                         These files are located in the Correlations subdirectory.
+                     

+                 

+                     

+                         << Previous  |  Next >>
+                 

+                     

+                         Use these buttons to navigate through the previous and next dialogs
+                         (if any).
+                     

+                     

+                         See which current dialog you are in, and to which other dialogs you
+                         connect, in the tab-like part at the top of the dialog under
+                         the title.
+                     

+                 

+                     

+                         Process
+                 

+                     

+                         Runs the
+                         fitting.
+                     

+                     

+                         This button remains 
+                             disabled until all the parameter
+                             dialogs have received enough (and consistent) informations
+                         .
+                 

+                     

+                         Cancel
+                 

+                     

+                         Quit the dialog.
+                 

+                     

+                         Help
+                 

+                     

+                         Launch the Help to the right page (should be here...).
+                 

+         

+             Fitting - Technical points & hints
+         

+         

+             Groups of Files in the Fitting
+         

+         

+             Groups of files can be of the same size or be of different sizes, depending
+             on you experiment and the type of statistics you are going to use.
+         

+         

+             If your groups have different size, meaning the number of subjects is not the
+             same across groupsn, then Cartool will force set the
+             within-subjects parameter to 1.
+         

+         

+              
+         

+         

+             The fitting is optimized to have the lowest memory footprint
+             and highest computation speed, and will load only the 
+                 absolute necessary files into memory at nay given time
+             . This allows you to have
+             any arbitrarily big groups of files to fit, even if they are original recording
+             (which can be large by themselves).
+         

+         

+             Number of consecutive within-subjects
+             groups
+         

+         

+             ('Group' here means a group of file you dropped in, and shown as such in the
+             list box)
+         

+         

+             A set of groups can (and actually should be) 
+                 grouped
+                 together
+              if they were part of a within-subjects paradigm.
+             Practically, this means that all the files from these groups were recorded
+             from identical subjects, row-wise speaking. It also implies that these groups
+             have the same number of files. F.ex. a paired experiment will be grouped by
+             2.
+         

+         

+             Once Cartool knows how many af these groups have to to joined together, it
+             will compute the normalization part (denominator part of the
+             equations) of the GEV  and
+             GFP normalization with all subject's files together. Again
+             for a paired experiment, the 2 files of a subject are used to compute the sum
+             of the squares of map, and the sum of GFP, which are therefor used to compute
+             the GEV and normalize by GFP respectively.
+         

+         

+             Failing to define properly the parameter will lead to a wrong normalization
+             of the data. If on the file has one more big component, it will relatively
+             make the other components looking artificially weaker, and hence could
+             produce erroneous positive tests on these components with their apparent
+             intensities difference.
+         

+         

+              
+         

+         

+             Cartool will suggest using the biggest denominator across all current groups'
+             sizes for this parameter. But you should check this is correct according to
+             your experiment design. With our example of a paired experiment, if you
+             dropped 4 files, and they are grouped by 2, then Cartool will run the fitting
+             on the groups 1 and 2 together, and then independently on the groups 3 and 4
+             together.
+         

+         

+             Variable names
+         

+         

+             The full variable names can have two different formats, namely the
+             short and the long versions. Choose the version according to the
+             program you are going to send the results to, though I think the long
+             version is clearer (Cartool can read both, however).
+         

+         

+             Variable names always consist of 3 parts joined together by a
+             "_" (underscore):
+         

+         
    
+             
  • 
+                 
    
+                     The group index
    
+             
  • The map / cluster index
    
+             
  • The variable computed
    
+         

+         

+             So f.ex.:
+         

+         
    
+             
  • 
+                 
    
+                     Long: Group1_Map1_NumTF, Group1_Map2_NumTF, Group1_Map1_MaxGfp...
    
+             
  • Short: G1_M1_N, G1_M2_N, G1_M1_X...
    
+         

+         

+              
+         

+         

+             The variables that can be computed are currently the
+             following. They can be further processed with 
+                 Cartool
+                 Statistics
+             , or the tools of your choice:
+         

+         

+              
+         

+         

+             

+                 
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                 

+                             Variable
+                         
+                             Meaning
+                         
+                             Unit
+                         
+                             Missing Value
+                         

+                             

+                                 First Onset
+                         

+                             

+                                 The first time frame of appearance, for a given map and a
+                                 given file.
+                             

+                         		
+                             

+                                 Time frame
+                             

+                         		
+                             

+                                 -1
+                         

+                             

+                                 Last Offset
+                         

+                             

+                                 The last time frame of appearance, for a given map and a given
+                                 file.
+                             

+                         		
+                             

+                                 Time frame
+                             

+                         		
+                             

+                                 -1
+                         

+                             

+                                 Number of TFs
+                         

+                             

+                                 Total number of time frames of appearance, for a given map and
+                                 a given file.
+                             

+                         		
+                             

+                                 Time frame
+                             

+                         		
+                             

+                                 0
+                         

+                             

+                                 Mean Correlation
+                         

+                             

+                                 Mean correlation, for a given map and a given file.
+                         

+                             

+                                 No unit
range in [-1..1]
+                             

+                         		
+                             

+                                 -1
+                             

+                         

+                             

+                                 GEV
+                         

+                             

+                                 
+                                     Global Explain Variance,
+                                     contribution splitted for each map, for a given file.
+                             

+                         		
+                             

+                                 No unit
range in [-1..1]
+                             

+                         		
+                             

+                                 0
+                             

+                         

+                             

+                                 TF of Centroid
+                         

+                             

+                                 The GFP-weighted mean time frame position, for a given map and a
+                                 given file.
+                             

+                         		
+                             

+                                 Time frame
+                             

+                         		
+                             

+                                 -1
+                             

+                         

+                             

+                                 Best Correlation
+                         

+                             

+                                 Highest Correlation
+                                 value encountered, for a given map and a given file...
+                             

+                         		
+                             

+                                 No unit
range in [-1..1]
+                             

+                         		
+                             

+                                 -1
+                             

+                         

+                             

+                                 TF of Best Correlation
+                         

+                             

+                                 ...and its position...
+                             

+                         		
+                             

+                                 Time frame
+                             

+                         		
+                             

+                                 -1
+                             

+                         

+                             

+                                 Gfp of TF of Best Correlation
+                         

+                             

+                                 ...and the Gfp value at that position.
+                             

+                         		
+                             

+                                 Identical to input data, usually [milli-volts]
+                             

+                         		
+                             

+                                 -1
+                             

+                         

+                             

+                                 Max Gfp
+                         

+                             

+                                 The max Gfp over the segment fit by a given map...
+                             

+                         		
+                             

+                                 Identical to input data, usually [milli-volts]
+                             

+                         		
+                             

+                                 0
+                             

+                         

+                             

+                                 TF of Max Gfp
+                         

+                             

+                                 ...and its position.
+                             

+                         		
+                             

+                                 Time frame
+                             

+                         		
+                             

+                                 -1
+                             

+                         

+                             

+                                 Mean Gfp
+                         

+                             

+                                 The mean G over the segment fit by a given map.
+                             

+                         		
+                             

+                                 Identical to input data, usually [milli-volts]
+                             

+                         		
+                             

+                                 0
+                             

+                         

+                             

+                                 Mean Duration
+                         

+                             

+                                 Mean length of segments.
+                             

+                         		
+                             

+                                 Millisecond
(older version was in time frame)
+                             

+                         		
+                             

+                                 0
+                             

+                         

+                             

+                                 Time Coverage
+                         

+                             

+                                 Percentage in time coverage, i.e. the number of time
+                                 frames for each template divided by the total number of labeled time frames
+                             

+                         		
+                             

+                                 Percentage [0..100]
(older version was in range [0..1])
+                             

+                         		
+                             

+                                 0
+                             

+                         

+                             

+                                 Segment Count Density
Occurences per second
+                                 in some papers
+                         

+                             

+                                 Number of segments divided by the total labeled duration.
+                             

+                         		
+                             

+                                 Count per second, not a frequency!
(older
+                                 version was in
+                                 count per time frame)
+                             

+                         		
+                             

+                                 0
+                             

+                         

+             

+         

+         

+             Markov Chains
+         

+         

+             The aim is to compute statistics on the transitions probabilities, to show
+             some kind of syntax in the sequences of micro-states. These
+             transitions are computed from the segments (all consecutive
+             time points of identical label stands for 1 state), and not on the
+             time frame level.
+         

+         

+             Cartool will output various Worksheets .csv files
+             which contain, for each subject, either the 
+                 expected probability from
+                 going to segment A to segment B
+             , or the 
+                 observed probability
+                 from the data
+             . Then we can compare the two statistically. The
+             expected probabilities are theoretical values based on the count of segments
+             for each template map. While the observed probabilities come from actually
+             scanning the transitions from each and every segment to all the others.
+         

+         

+              
+         

+         

+             Cartool will output 2 types of probabilities, the difference between the two
+             being how the probabilities are normalized:
+         

+         
    
+             
  • 
+                 Markov probabilities: the 
+                     sum
+                     of all probabilities for each line of the transition matrix is equal to 1
+                 .
    
+                 F.ex. showing below the observed values (6 maps + Unlabeled):
    
+                 
+             
    • 
+             
  • 
+                 Joint States Probabilities: the 
+                     sum of all probabilities of the whole transition matrix is equal to 1
+                 .
    
+                 F.ex. showing below the observed values (6 maps + Unlabeled):
    
+                 
+             
    • 
+         

+         
 

+         

+             Note 1: In case a 
+                 minimum correlation
+                 threshold has been set
+             , we end up with an additional "state", the one
+             with undefined labeling. Undefined data points are the one which don't
+             correlate well enough to any template maps. It is a sort of "garbage"
+             cluster, so to speak. It behaves like a regular cluster for all the
+             transition probabilities computation, though.
+         

+         

+             Note 2: The number of transitions ahead is which segment is
+             considered the one to compute the transition to. Default is 1, which means
+             the next segment. If you set to a higher value, like 2, the second-next
+             segment will be used. This is not the traditional Markov order.
+         

+         

+             Duration histograms
+         

+         

+             Two files per subject are outputed, one with linear and one with log time
+             scale: 
+         

+         

+             
+         

+         

+             
+         

+         

+             You can run statistics on the duration histograms.
+         

+         

+             Segments frequency
+         

+         

+             This option will create a new time line for each map (top picture), where each
+             segment (bottom picture) is replaced by a raised cosine bump. Here you can
+             focus at map 1 as a good example:
+         

+         

+             
+         

+         

+             
+         

+         

+             This can be used for frequency analysis.
+         

+         

+             Correlation output
+         

+         

+             Across time correlation shows the 
+                 correlation between each template
+                 map and every data point
+             . Values are within the [0..1] range:
+         

+         

+             
+         

+         

+              
+         

+         

+             Once we have these time lines, we can again correlate them. This will show
+             how each correlation time course looks similar to the other ones
+             (which is not to be confused with the correlation between maps):
+         

+         

+             
+         

+         

+             Fitting - Results
+         

+         
    
+             
  • 
+                 
    
+                     A .vrb verbose file,
+                     containing all the parameters being used, plus the GFP normalization factors
+                     computed
+                     per file(s), if the option was selected.
+                 
    
+             
  • 
+                 
    
+                     A copy of the input templates .ep
+                     and its corresponding .seg
+                     files.
+                 
    
+             
  • 
+                 
    
+                     Then for each group of files:

    
+                 
    
+                 
      
+                     
    • 
+                         
      
+                             In the root directory, 1 or n .csv files,
      
+                             
+                                 
+                                        
+                                     <basefilename>.Group<#>.LinesAsSamples.csv
+                                 
+                                    and / or
      
+                             
+                                 
+                                        
+                                     <basefilename>.Group<#>.FactorsAsColumns.csv
      
+                                       
+                                   each
+                             file containing all the output variables, arranged
+                             in different layouts to match your
+                             analysis tools.
      
+                         
      
+                     
    • 
+                         
      
+                             In the root directory,
          <basefilename>.Group<#>.seg
+                             
      is the labeling file of all subjects together (only in case of
+                             non-competitive fitting BTW)
      
+                         
      
+                     
    • 
+                         
      
+                             In the Segmentations directory,
          <basefilename>.Group<#>.Subj<#>      .seg      
+                             
      contain labeling split by subject.
      
+                         
      
+                     
    • 
+                         
      
+                             In the Data Clusters directory,
          
+                                 
+                                     <basefilename>.Subject<#>.<original
+                                     file name>.Cluster<#>.*.sef
+                                 
+                             
      contain all the maps
+                             assign to a given cluster.
      
+                         
      
+                     
    • 
+                         
      
+                             In the Markov Chains directory, and in case of
+                             Markov output,
+                         
      
+                         
        
+                             
      • 
+                                 
        
+                                     <basefilename>.Group<#>.MarkovChains<#>.*.csv
+                                     files .
        Each
+                                     file contains the probabilities of  transitions (templatei →
+                                     templatej),
+                                     with 1 file for each step ranging from 1 to the maximum set in the
+                                     parameters.
        The format of the .csv
+                                     follows these options.
+                                 
        
+                             
      • 
+                                 
        
+                                     <basefilename>.Group<#>.MarkovChains.freq
+                                     files.
        These are the same data as the above .csv
+                                     files, but all transitions are stored (trick) into a .freq file. In this case, the "frequency" dimension
+                                     will hold the transitions dimension, the "time" dimension will
+                                     will hold the subjects index dimension.
        
+                                 
        
+                         
      
+                     
    • 
+                         
      
+                             In the Histograms Duration directory,
         
+                             <basefilename>.Subject<#>.HistoDuration.Lin.sef  
+                             and
          <basefilename>.Subject<#>.HistoDuration.Log.sef      
+                             
      contain the histograms of segments' durations.
      
+                         
      
+                     
    • 
+                         
      
+                             In the Segments Frequency directory, and
+                             in case of 
+                                 segments frequency
+                                 output
+                             , 
          <basefilename>.Group<#>.Subj<#>.SegFreq.sef
      files
+                             hold the segments coded as bumps, with 1 track per template,
+                             reflecting the frequency of the fit templates.
      
+                         
      
+                     
    • 
+                         
      
+                             In the Correlations directory, and in case of
+                             correlation output,
          <basefilename>.Group<#>.Subj<#>.CorrDataTempl      .sef
      
+                                 <basefilename>.Group<#>.Subj<#>.CorrTempl.sef
      
+                             files
+                             hold the correlations of the data with each template, and the
+                             correlation of the correlations.
+                         
      
+                 
    
+         

+         

+              
+         

+         

+             Also see the technical points, and
+             especially the GEV remarks.
+         

+         

+             Format of the .csv results
+         

+         

+             As for today, there are 2 output arrays, each with a 
+                 different formatting
+              and targetting different packages. They however
+             contain exactly the same data, this is just a matter of
+             formatting the 4D (number of groups x number of subjects x
+             number of segments x number of variables) dataset...
+         

+         

+              
+         

+         

+             The .LinesAsSamples.csv file
+         

+         

+             Each line correspond to a subject, so the number of subjects
+             is equal to the total number of lines - 1 (the header line).
+         

+         

+             This is the format used by Cartool and
+             Statistica for its statistical analysis.
+         

+         

+             With this format, lines end up to be huge, and sometimes will fail to be read
+             by Excel, though Cartool and other analysis packages will have no
+             problems reading them.
+         

+         

+              
+         

+         

+             The format is the following:
+         

+         
    
+             
  • 
+                 
    
+                     First line is a header which lists all the 
+                         mutliplexed variables' name
+                     . First variable name is always 
+                         Subject
+                     , then there are many variables with format of the like 
+                         Group*_Map*_VariableName
+                     .
+             
  • 
+                 
    
+                     Next lines hold the data themselves, with 1 row/line per
+                     subject (so each line can be quite long):
      
+                         
    • 
+                             
      
+                                 Data are mulitplexed by Group, then Map, then Variable, in this
+                                 order from outer to inner variable loop.
      F.ex. you'll find first
+                                 all the variables of Group1, Map1, then all the variables of Group1,
+                                 Map2, etc.. for all maps, then all the variables of Group2, Map1, then
+                                 all the variables of Group2, Map2, etc...
+                         
    • 
+                             
      
+                                 Data are written either in integer or floatting point, according to
+                                 their actual types (integer for counts f.ex., floatting point for GEV,
+                                 Gfp etc...)
+                     
    
+         

+         

+              
+         

+         

+             Here is an example of the actual ordering (the formatting
+             itself is skipped for clarity), for 3 files, 2 groups, 2 maps, and 2
+             variables (NumTF and Gfp). The names in italic indicate
+             some actual data:
+         
File1	Group1_Map1_NumTF  Group1_Map1_MaxGfp  Group1_Map2_NumTF  Group1_Map2_MaxGfp  Group2_Map1_NumTF  Group2_Map1_MaxGfp  Group2_Map2_NumTF  Group2_Map2_MaxGfp
File2	Group1_Map1_NumTF  Group1_Map1_MaxGfp  Group1_Map2_NumTF  Group1_Map2_MaxGfp  Group2_Map1_NumTF  Group2_Map1_MaxGfp  Group2_Map2_NumTF  Group2_Map2_MaxGfp
File3	Group1_Map1_NumTF  Group1_Map1_MaxGfp  Group1_Map2_NumTF  Group1_Map2_MaxGfp  Group2_Map1_NumTF  Group2_Map1_MaxGfp  Group2_Map2_NumTF  Group2_Map2_MaxGfp

+         
 

+         

+             The .ColumnsAsFactors.csv file
+         

+         

+             Each column is a factor / variable.
+         

+         

+             This is the format used by R.
+         

+         

+             With this format, and contrary to the Lines As Samples format above, lines
+             are hopefully much shorter. The counterpart is that the number of lines is
+             much higher, and you have to make sure that all combinations of Files, Groups
+             and Maps indexes exist (like the indexes of a 3D array).
+         

+         

+              
+         

+         

+             The format is the following:
+         

+         
    
+             
  • 
+                 
    
+                     First line is a header which lists all the 
+                         variables' name
+                     . First variables names are always Subject,
+                     Group and Map, then followed by all the
+                     variables names.
+             
  • 
+                 
    
+                     Next lines hold the data themselves:
      
+                         
    • 
+                             
      
+                                 The first 3 values hold the file name, group
+                                 index, and map index, all in text.
      F.ex.    File1   
+                                 Group2    Map5
+                         
    • 
+                             
      
+                                 Next are all the variables values, in the order listed
+                                 from the header line.
+                         
    • 
+                             
      
+                                 Data are not necessarily ordered, though they are currently written
+                                 first by Group, then by Map, then by Variable.
+                     
    
+         

+         

+              
+         

+         

+             Here is an example of the actual ordering (the formatting
+             itself is skipped for clarity), for 3 files, 2 groups, 2 maps, and 2
+             variables (NumTF and Gfp). The names in italic indicate
+             some actual data:
+         

+         
File1	Group1	Map1	Group1_Map1_NumTF  Group1_Map1_MaxGfp
 File1	Group1	Map2	Group1_Map2_NumTF  Group1_Map2_MaxGfp
 File1	Group2	Map1	Group2_Map1_NumTF  Group2_Map1_MaxGfp
 File1	Group2	Map2	Group2_Map2_NumTF  Group2_Map2_MaxGfp
@@ -1657,69 +2166,104 @@ 

 File3	Group1	Map2	Group1_Map2_NumTF  Group1_Map2_MaxGfp
 File3	Group2	Map1	Group2_Map1_NumTF  Group2_Map1_MaxGfp
 File3	Group2	Map2	Group2_Map2_NumTF  Group2_Map2_MaxGfp

-  

-   Fitting in the Inverse Solution space

-  
This is the counterpart of the segmentation in 
-   the Inverse Solution space. Instead of fitting the subjects' ERPs 
-   with the template maps from the segmentation, we can fit the 
-   Results
-    on Inverse Solution .ris 
-  files with .ris templates 
-  obtained from the segmentation in the inverse space.

-  
-  

-   <This part has to be totally rewritten>

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    
+         

+             Fitting in the Inverse Solution space
+         

+         

+             This is the counterpart of the 
+                 segmentation in
+                 the Inverse Solution space
+             . Instead of fitting the subjects' ERPs
+             with the template maps from the segmentation, we can fit the
+             
+                 Results
+                 on Inverse Solution
+              .ris
+             files with .ris templates
+             obtained from the segmentation in the inverse space.
+         

+         
+             
+                 

+                     <This part has to be totally rewritten>
+                 

+                 

+                      
+                 

+                 

+                      
+                 

+                 

+                      
+                 

+                 

+                      
+                 

+                 

+                      
+                 

+                 

+                      
+                 

+                 

+                      
+                 

+                 

+                      
+                 

+                 

+                      
+                 

+                 

+                      
+                 

+                 

+                      
+                 

+                 

+                      
+                 

+                 

+                      
+                 

+                 

+                      
+                 

+                 

+                      
+                 

+                 

+                      
+                 

+                 

+                      
+                 

+                 

+                      
+                 

+                 

+                      
+                 

+                 

+                      
+                 

+                 

+                      
+                 

+                 

+                      
+                 

+                 

+                      
+                 

+                 

+                      
+                 

+                 

+                      
+                 

+                 

+                      
+     

  
 
\ No newline at end of file
diff --git a/docs/ReferenceGuide/microstates-segmentation-display.html b/docs/ReferenceGuide/microstates-segmentation-display.html
index dcc3bb12..4154d6bc 100644
--- a/docs/ReferenceGuide/microstates-segmentation-display.html
+++ b/docs/ReferenceGuide/microstates-segmentation-display.html
@@ -8,323 +8,462 @@
 }
 
  
- 
-  

-   Segments Display

-  

-    

-  

-    After the Segmentation Process,
-    we have these files:

-  

-    

-  

-   The Segments display, for a single segmentation

-   The summary of a set of segmentations

-  

-   Segments display

-  

-   This display applies to the .seg 
-   (Segments) files. It is exactly the same as the EEG
-    display, with just a few more options.

-  

-   Menus

-  

-   Options

-  
-  

-   Technical points

-  

-   Full file content

-  

-   Segments display - Menus

-  

-   Quite the same as the EEG Menus, with the 
-   following variations or additions:

-  

-   Options menu

-  
    
-   
    
-    No / Empty / Colored Filling
    
-   
      
-    
      
-     You can change the coloring scheme to these modes:
      
-    
        
-     
      • 
-     
        
-      No: No filling, just plain tracks.
        
-     
        
-      
        
-     
      • 
-     
        
-      Empty: The colors are replaced by an empty color (usually 
-      white), and the segments are separated by black lines (useful if you 
-      want to apply your own colors, or give it to your little nephew so 
-      you have 5 minutes of silence).
        
-     
        
-      
        
-     
      • 
-     
        
-      Colored: The default colored display. Note that the colors 
-      picked depend on the number of segments, so the color for segment 3 
-      will differ if it belongs to different segmentations.
        
-     
        
-      
        
-     
      
-    
    
-   
    
-    Select Segments from list
    
-   
      
-    
      
-     You can restrict which segments will be actually colored, to focus 
-     the display on the segments of interest. Just give the list of 
-     segments you want to see, or empty to reset.
      
-    
        
-     
        
-      
        
-     
      
-    
    
-   
    
-    Select Segments from cursor position
    
-   
      
-    
      
-     This will automatically select the only segments that overlap the current 
-	 cursor position.
      
-    
    
-   

-  

-   Segments display - Technical points

-  

-   Full file content

-  

-   Actually, the .seg 
-   file contains more informations than just the colored segments. When 
-   the file opens in Cartool, they are not shown to make the display 
-   clearer. To see all these informations, simply click on More
-    Tracks button, from the EEG display.

-  

-   These informations can also be retrieved for some processings of your own...

-  

-   For each of the file that has been segmented, you have the following 
-   informations (in this order):

-  
-  

-    

-  

-   See an example, for two conditions, of the restricted initial 
-   display, and the full display. Note that the original file names 
-   are lost ("Condition1", "Control" f.ex.), so 
-   you have to remember the order in which you inputed the data to the 
-   segmentation process. GFP1, Dis1, Seg1, GEV1 and Corr1 are for the 
-   first condition / file, GFP2, Dis2 etc for the second condition / 
-   file, and so on:

-  
    
-   
      
-    
        
-     
        
-      
        
-      
        
-     
      
-    
    
-   

-  

-   The coloring schemes used are the following:

-  
    
-   
  • 
-   
    
-    For the GFP and Dis tracks, a discrete color is 
-    assigned according to the value of the labeling (contained in 
-    the Seg track). The colors are choosen to be the "furthest" 
-    from each others. They also depend on the maximum number of clusters, 
-    so that the color of segment 3 (f.ex.) in two different segmentations 
-    will look different.
    
-   
  • 
-   
    
-    For the Seg track, a proportional coloring based on the GEV 
-    (the following track, by the way) is used. The higher the GEV, the 
-    brighter the segment (from black to yellow).
    
-   

-  

-   Summary of segmentations

-  

-   The .error.data file 
-   generated at the end of the Segmentation shows 
-   different error measures 
-   across the specified range of clusters. Its purpose is to help decide which 
-   is the optimal number of clusters, based on these measures.

-  

-   It contains the following 
-   tracks, with the horizontal axis ranging from 1 to the max number of 
-   clusters:

-  
-  

-    

-  

-   

-  

-    

-  

-   The display is also based on the EEG display,
-    with just a few more options:

-  

-   Menus

-  

-   Options

-  
-  

-   Technical points

-  

-   Number of clusters vs number of maps

-  

-   Error measures

-  

-   The Optimal number of clusters & 
-   Meta-Criterion

-  

-   Summary of segmentations - Menu

-  

-   Quite the same as the EEG Menus, with the 
-   following variations or additions:

-  

-   Options menu

-  
    
-   
    
-    Open Segmentation(s) at cursor position
    
-   
      
-    
      
-     A shortcut to directly open the Segments files 
-     corresponding to where the cursor is located. If more than one 
-     position is selected, all the files are opened.
      
-    
    
-   

-  

-   Summary of segmentations - 
-   Technical points

-  

-   Number of Clusters vs number 
-   of Maps

-  

-   There is a semantic distinction done here between the number of 
-   clusters and the number of segments:

-  
    
-	  
  • The number of clusters is the input 
-	  given to the clustering, the 
-	  range specified by the user. It always shows up a straight line, of 
-	  slope 1.
    • 
-	  
  • The number of segments is the final number of 
-	  clusters after the optional temporal post-processing. These 
-	  options could create more clusters, as per the
-	  Sequentialization, or 
-	  delete some, as per the 
-	  Reject Small Segments.
    Without any post-processing, clusters and 
-	  segments are totally equivalent.
    • 
-  

-  

-    

-  

-   Below we can see the number of clusters (black line) vs. the number 
-   of segments (violet line), showing that the temporal post-processing did 
-   alter the number of clusters:

-  

-   

-  

-   Error measures

-  

-   The Global Explained Variance (GEV) is a global measure of the 
-   quality of a given segmentation. It converges asymptotically toward
-    1 (perfect segmentation) as the number of clusters increases. 
-   Note that this value of 1 can only be reached if the number of 
-   clusters is equal to the number of time frames.

-  

-   The other measures are explained 
-   here.

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    
+ 
+     

+         

+             Segments Display
+         

+         

+              
+         

+         

+              After the Segmentation Process,
+             we have these files:
+         

+         

+              
+         

+         

+             The Segments display, for a single segmentation

+             The summary of a set of segmentations
+         

+         

+             Segments display
+         

+         

+             This display applies to the .seg
+             (Segments) files. It is exactly the same as the 
+                 
+                     EEG
+                     display
+                 
+             , with just a few more options.
+         

+         

+             Menus
+         

+         

+             Options
+         

+         
+         

+             Technical points
+         

+         

+             Full file content
+         

+         

+             Segments display - Menus
+         

+         

+             Quite the same as the EEG Menus, with the
+             following variations or additions:
+         

+         

+             Options menu
+         

+         
    
+             
    
+                 No / Empty / Colored Filling
+             
    
+             
      
+                 
      
+                     You can change the coloring scheme to these modes:
+                 
      
+                 
        
+                     
      • 
+                         
        
+                             No: No filling, just plain tracks.
+                         
        
+                         
        
+                             
+                         
        
+                     
      • 
+                         
        
+                             Empty: The colors are replaced by an empty color (usually
+                             white), and the segments are separated by black lines (useful if you
+                             want to apply your own colors, or give it to your little nephew so
+                             you have 5 minutes of silence).
+                         
        
+                         
        
+                             
+                         
        
+                     
      • 
+                         
        
+                             Colored: The default colored display. Note that the colors
+                             picked depend on the number of segments, so the color for segment 3
+                             will differ if it belongs to different segmentations.
+                         
        
+                         
        
+                             
+                         
        
+                 
      
+             
    
+             
    
+                 Select Segments from list
+             
    
+             
      
+                 
      
+                     You can restrict which segments will be actually colored, to focus
+                     the display on the segments of interest. Just give the list of
+                     segments you want to see, or empty to reset.
+                 
      
+                 
        
+                     
        
+                         
+                     
        
+                 
      
+             
    
+             
    
+                 Select Segments from cursor position
+             
    
+             
      
+                 
      
+                     This will automatically select the only segments that overlap the current
+                     cursor position.
+                 
      
+             
    
+         

+         

+             Segments display - Technical points
+         

+         

+             Full file content
+         

+         

+             Actually, the .seg
+             file contains more informations than just the colored segments. When
+             the file opens in Cartool, they are not shown to make the display
+             clearer. To see all these informations, simply click on 
+                 More
+                 Tracks
+              button, from the EEG display.
+         

+         

+             These informations can also be retrieved for some processings of your own...
+         

+         

+             For each of the file that has been segmented, you have the following
+             informations (in this order):
+         

+         
+         

+              
+         

+         

+             See an example, for two conditions, of the restricted initial
+             display, and the full display. Note that the 
+                 original file names
+                 are lost
+              ("Condition1", "Control" f.ex.), so
+             you have to remember the order in which you inputed the data to the
+             segmentation process. GFP1, Dis1, Seg1, GEV1 and Corr1 are for the
+             first condition / file, GFP2, Dis2 etc for the second condition /
+             file, and so on:
+         

+         
    
+             
      
+                 
        
+                     
        
+                         
        
+                         
+                     
        
+                 
      
+             
    
+         

+         

+             The coloring schemes used are the following:
+         

+         
    
+             
  • 
+                 
    
+                     For the GFP and Dis tracks, a discrete color is
+                     assigned according to the value of the labeling (contained in
+                     the Seg track). The colors are choosen to be the "furthest"
+                     from each others. They also depend on the maximum number of clusters,
+                     so that the color of segment 3 (f.ex.) in two different segmentations
+                     will look different.
+                 
    
+             
  • 
+                 
    
+                     For the Seg track, a proportional coloring based on the GEV
+                     (the following track, by the way) is used. The higher the GEV, the
+                     brighter the segment (from black to yellow).
+                 
    
+         

+         

+             Summary of segmentations
+         

+         

+             The .error.data file
+             generated at the end of the Segmentation shows
+             different error measures
+             across the specified range of clusters. Its purpose is to help decide which
+             is the optimal number of clusters, based on these measures.
+         

+         

+             It contains the following
+             tracks, with the horizontal axis ranging from 1 to the max number of
+             clusters:
+         

+         
+         

+              
+         

+         

+             
+         

+         

+              
+         

+         

+             The display is also based on the EEG display,
+             with just a few more options:
+         

+         

+             Menus
+         

+         

+             Options
+         

+         
+         

+             Technical points
+         

+         

+             Number of clusters vs number of maps
+         

+         

+             Error measures
+         

+         

+             
+                 The Optimal number of clusters &
+                 Meta-Criterion
+             
+         

+         

+             Summary of segmentations - Menu
+         

+         

+             Quite the same as the EEG Menus, with the
+             following variations or additions:
+         

+         

+             Options menu
+         

+         
    
+             
    
+                 Open Segmentation(s) at cursor position
+             
    
+             
      
+                 
      
+                     A shortcut to directly open the Segments files
+                     corresponding to where the cursor is located. If more than one
+                     position is selected, all the files are opened.
+                 
      
+             
    
+         

+         

+             Summary of segmentations -
+             Technical points
+         

+         

+             Number of Clusters vs number
+             of Maps
+         

+         

+             There is a semantic distinction done here between the 
+                 number of
+                 clusters
+              and the number of segments:
+         

+         
    
+             
  • 
+                 The number of clusters is the input
+                 given to the clustering, the 
+                     range specified by the user
+                 . It always shows up a straight line, of
+                 slope 1.
+             
    • 
+             
  • 
+                 The 
+                     number of segments is the final number of
+                     clusters after the optional temporal post-processing
+                 . These
+                 options could create more clusters, as per the
+                 Sequentialization, or
+                 delete some, as per the 
+                     Reject Small Segments
+                 .
    Without any post-processing, clusters and
+                 segments are totally equivalent.
+             
    • 
+         

+         

+              
+         

+         

+             Below we can see the number of clusters (black line) vs. the number
+             of segments (violet line), showing that the temporal post-processing did
+             alter the number of clusters:
+         

+         

+             
+         

+         

+             Error measures
+         

+         

+             The Global Explained Variance (GEV) is a global measure of the
+             quality of a given segmentation. It converges asymptotically 
+                 toward
+                 1
+              (perfect segmentation) as the number of clusters increases.
+             Note that this value of 1 can only be reached if the number of
+             clusters is equal to the number of time frames.
+         

+         

+             The other measures are 
+                 explained
+                 here
+             .
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+     

  
 
\ No newline at end of file
diff --git a/docs/ReferenceGuide/microstates-segmentation.html b/docs/ReferenceGuide/microstates-segmentation.html
index 4c71dec8..78972d1f 100644
--- a/docs/ReferenceGuide/microstates-segmentation.html
+++ b/docs/ReferenceGuide/microstates-segmentation.html
@@ -26,1917 +26,2600 @@
 }
 
  
- 
-  

-   Segmentation of EEG Files into Micro-States

-  

-    

-  

-   Segmentation is run first to extract template 
-   maps, which can be back-fit to the individual 
-   subjects on a second stage.

-  

-    

-  

-   Brief introduction to the segmentation

-   Segmentation of EEG files into micro-states

-  
-  

-   How to run the Segmentation

-  

-   Files Dialog

-   Parameters Dialog

-  

-   Technical points & hints

-   Results

-   Segmentation in the Source Space

-  

-   Brief introduction to the segmentation

-  

-   Segmentation into micro-states is 
-   the process of finding periods of stability in the map 
-   representation of the ERP's. The data (usually grand means) are then segmented
-    / cut where changes occur, and template maps are computed 
-   for each of the resulting segments to 
-   act as single representatives of the segments. The segmentation 
-   therefore produces:

-  
    
-   
  • 
-   
    
-    a labeling for each time 
-    point and for each file, asserting to which segment it belongs to,
    
-    
  • a set of template (synthetic) maps that best 
-    represent each segment.
    
-   

-  

-    

-  

-   Given a set of averaged maps, it is possible to fit 
-   them back onto individual ERP's:

-  
    
-   
  • 
-   
    
-    for each time point, it chooses which map 
-    fits the best, producing again a labeling,
    
-    
  • some variables are then extracted from this 
-    "fitting", such as the number of occurrence for each map, 
-    the first occurrence for each map, or when a given map was best 
-    fit. These variables are then used for statistics.
    
-   

-  

-    

-  

-   For the display of the segmentation, see all the Segments
-    Display.

-  

-   Segmentation of EEG files into micro-states

-  

-   Methods used for the segmentation

-  

-   It is actually made of three successive steps:

-  
    
-   
  1. 
-   
    
-    A mathematical clustering,
    
-    
  2. Some temporal post-processings,
    
-    
  3. Computing some quality measures.

-  

-    

-  

-   Let's introduce briefly these three points:

-  

-   1. Mathematical clustering

-  

-   This is a well-known mathematical process, which does not 
-   account for the time dimension of the data. That is, data (maps) are 
-   put in a "bag", then picked from there without caring for 
-   their actual time stamp. Three methods are available for this stage:

-  
-  

-   2. Temporal post-processings

-  

-   These are optional processings, which have the nice 
-   properties, for most of them, to account for the time dimension. They 
-   are totally independent of the type of clustering method used in the 
-   first stage. The methods available are (in this order):

-  
-  

-   3. Computing clustering quality measures

-  

-   Cartool computes 9 different clustering quality criteria (as 
-   of 2024), and then combine them into a meta-criterion. This 
-   meta-criterion has a statistically more robust behavior, i.e. it outperforms 
-   each individual single criteria alone for correctly guessing the optimal 
-   number of clusters.

-  

-   See the full discussion about clustering 
-   criteria.

-  

-    

-  

-   Next, we are going to delve into the details of these three stages.

-  

-   Mathematical clustering

-  

-   The K-Means clustering

-  

-   We summarize here the K-Means algorithm as it is used for the EEG 
-   data in Cartool. For the sake of clarity, we use practical numbers, 
-   by searching for 5 clusters out of 4 conditions of 100 time frames. 
-   Time is not relevant in this algorithm, so the total of 400 maps 
-   are just "put into a bag".

-  

-    

-  
    
-   
  1. 
-   
    
-    Initialization
    
-   
      
-    
    • 
-    
      
-     Of the templates: randomly pick 5 
-     non-identical maps out of the 400 data maps.
      
-    
    • 
-    
      
-     Of the labeling: test each of the 400 
-     maps, and label (index) to which of the 5 templates they correlate 
-     the most.
      
-    
    
-   
  2. 
-   
    
-    Convergence loop
    
-   
      
-    
    • 
-    
      
-     Compute new templates: average all the maps that have the same label.
      
-    
    • 
-    
      
-     Compute new labeling: test each of the 400 maps, and label 
-     (index) to which of the 5 new templates they correlate the most.
      
-    
    • 
-    
      
-     Compute a measure of quality of the current labeling (Global
-      Explained Variance, GEV).
      
-    
    
-   
  3. 
-   
    
-    Repeat step 2, until the GEV doesn't improve anymore.
    
-   
  4. 
-   
    
-    If the end results has a higher GEV than the current best one, keep 
-    it as the current best.
    
-   
  5. 
-   
    
-    Repeat again steps 1 to 4, until enough repetitions have been done.
    
-   

-  

-    

-  

-   At the end, we have an estimate of the theoretically best segmentation.

-  

-   As there is a random stage in this algorithm, we can only get close 
-   to the perfect solution. Also, running again the whole stuff will 
-   give slightly different results for the same reason. However, the 
-   process is reliable and is a standard procedure. See more technical
-    points here.

-  

-   The Atomize & Agglomerate 
-   Hierarchical Clustering (AAHC)

-  

-   Important note: the AAHC is not used anymore in Cartool, only 
-   its modified version T-AAHC is available. 
-   However, the T-AAHC being based on the AAHC, the explanations below 
-   still hold.

-  

-    

-  

-   The usual Hierarchical
-    Agglomerative Clustering is a bottom-up approach. It starts with 
-   all maps being a cluster, then it merges the two closest clusters (of 
-   the current remaining ones) into a new one, repeatively. In this way, 
-   we have all the segmentations from the number of Time Frames down to 1.

-  

-   Cartool implements a modified version of the Hierarchical 
-   clustering, specifically tailored for the EEG case, called the Atomize
-    & Agglomerate Hierarchical Clustering (AAHC).

-  

-   It behaves the same as a regular hierarchical agglomerative 
-   clustering, starting with every map being a cluster. Then the main 
-   idea is to pick the "worst" segment of all currently 
-   availables, to atomize it (split it into indivividual maps), and to 
-   re-distribute these maps to the segments they fit most. This also 
-   results in all the segmentations from the number of Time Frames 
-   downto 1.

-  

-    

-  
    
-   
  1. 
-   
    
-    Initialization
    
-   
      
-    
    • 
-    
      
-     Of the templates: each map is a template, starting therefore with 400 clusters.
      
-    
    • 
-    
      
-     Of the labeling: each map labels itself.
      
-    
    
-   
  2. 
-   
    
-    Removing one cluster
    
-   
      
-    
    • 
-    
      
-     Pick the worst cluster: the one with the lowest GEV
-      (Global Explained Variance).
      
-    
    • 
-    
      
-     Atomize & distribute: take each map of this cluster, and 
-     assign it to the remaining cluster it correlates the best.
      
-    
    • 
-    
      
-     Compute new labeling: test each of the 400 maps, and label 
-     (index) to which of the remaining templates they correlate the most.
      
-    
    
-   
  3. 
-   
    
-    Repeat step 2, removing one cluster at a time, until we reach 5 clusters.
    
-   

-  

-    

-  

-   The main advantages of this method over the regular Hierarchical 
-   Agglomerative Clustering are:

-  
    
-   
  • 
-   
    
-    It redefines the boundaries at each step, allowing small segments 
-    to remain.
    
-    
  • It gives a far better GEV on each segmentation, 
-    leading to a better choice of the optimum
-     segmentation.
    
-   

-  

-   There are many advantages of this method over the K-Means:

-  
    
-   
  • 
-   
    
-    It gives always the same results, if run again.
    
-    
  • It runs much faster.
    
-    
  • It spends its "segmentation power" into 
-    higher GFP areas, then giving the interesting segments earlier.
    
-   

-  

-    

-  

-   A final word could be: try both segmentations, and see the 
-   differences by yourself, it's not good to trust blindly (even 
-   Cartool). Actually, if there is something in your data, it will show 
-   up with both methods anyway!

-  

-    

-  

-   See f.ex. a AAHC versus a K-Means for 18 segments 
-   (though it could be hard to compare directly):

-  

-   

-   

-  

-   The Topographic Atomize & Agglomerate 
-   Hierarchical Clustering (T-AAHC)

-  

-   The T-AAHC is actually a further refinement of the above AAHC. The 
-   main difference being that the T-AAHC does not account for the 
-   powers of the maps, but only for their topographies, as the 
-   K-Means was doing.

-  

-   Though the power of maps can be significantly used in many cases, 
-   there are other cases where they are not. If a given brain area is 
-   activated with only a low power, still, this is an interesting event 
-   to consider. Or if you want to re-segment a bunch of template maps 
-   merged together, they all have the same GFP so power is of no help in 
-   this case.

-  

-   The T-AAHC takes the best of both the K-Means, by working only 
-   topographies, and the AAHC, by being deterministic and fast, 
-   without their respective drawbacks.

-  

-    

-  

-   There is actually only one technical difference between the T-AAHC 
-   and the AAHC. At one point, both methods have to pick "the worst 
-   cluster" before atomizing it and re-distributing its parts to 
-   the other clusters:

-  
    
-   
  • 
-   
    
-    The AAHC picks the cluster with the lowest GEV (Global 
-    Explained Variance), in which the GFP of course comes into account.
    
-   
  • 
-   
    
-    The T-AAHC picks the "less explained" cluster, the 
-    one whose maps correlate the worse to its template (cluster with the 
-    lowest sum of correlation).
    
-   

-  

-    

-  

-   The T-AAHC results are very close to the K-Means ones, see here an 
-   example for 15 segments (first one is the T-AAHC, second one is the K-Means):

-  

-   

-   

-  

-   Temporal post-processings

-  

-   Temporal smoothing

-  

-   This was the historical way to remove small segments. We kept it 
-   here, but we do prefer the Small maps rejection 
-   procedure instead, because its actual behavior is difficult to 
-   predict (very parameter dependent).

-  

-   (You can refresh your memory with all the formulas
-    here)

-  

-   In the labeling process, when assigning a map  
-   for each time point t, a distance d is computed, and 
-   the map with the lowest distance d chosen:

-   

-   To express the idea that micro-states tend to stay stables, we 
-   introduce a smoothing factor in the distance d, by defining a 
-   new distance d' that has to minimized the same way:

-   

-   with Nbkt being the number of maps k in the 
-   interval t-b to t+b (excluding time t itself), 
-   and >0
-    being a weighting factor to control the smoothness.  
-   equal to 0 gives d' = d, while greater values will 
-   allow more smoothness. b is a window size, before and after 
-   current time point t.

-  

-    

-  

-    See f.ex. before and after a smoothing (Window half size of 3, 
-   strength of 10). Note that not all small segments have been removed:

-  

-   

-  

-   Sequentialization

-  

-   The mathematical clustering, as already explained,
-    does not account for the time dimension. It therefore happens very 
-   often that maps attributed to a given cluster be in fact spread 
-   into very distinct time windows. See for example here cluster 3,
-    or cluster 4:

-  

-   

-  

-    

-  

-   The clustering did a good job grouping maps together, as the best 
-   trade-off for 8 clusters. But based on physiological evidences, 
-   segments sharing the same label but being temporaly 
-   disconnected do not reflect the same neuronal activity. We are 
-   then untitled to sequentialize those parts, i.e. to split the 
-   clusters with many non-overlapping windows into some sub-clusters.

-  

-    

-  

-   The second generation of the sequentialization process works this way:

-  
    
-   
  • 
-   
    
-    For each cluster index:
    
-   
      
-    
    • 
-    
      
-     If there is at most one part of that cluster for each file, do 
-     nothing and continue to the next cluster.
      
-    
    • 
-    
      
-     "Cumulate vertically" all files for that cluster, to get a 
-     labeling telling for each time frame if that cluster has been found 
-     in at least one of the files.
      
-    
    • 
-    
      
-     Use this labeling to split the cluster into its timely disconnected parts.
      
-    
    
-   

-  

-    

-  

-   See here the original clustering without sequentialization (above), 
-   then with sequentialization (below). Worth of interest is the 
-   splitting of old cluster 1 into new 1 and 9, old cluster 6 into new 7 
-   and 11, old cluster 7 into new 13, 15 and 16. Also note that old 
-   cluster 8 remains unchanged (though renamed 14) due to the fact that 
-   all its parts overlap:

-  

-   

-   

-  

-    

-  

-   Merging correlated maps

-  

-   This procedure blindy merges together all maps that are correlated 
-   above a specified threshold. To be used when you really want to force 
-   (and only when) the merging of some segments together.

-  

-   Not to be confused with the re-merge step of the Sequentialization.
-    This is another, and independent, processing.

-  

-    

-  

-   See f.ex. before and after merging maps above a correlation of 0.92:

-  

-   

-   

-  

-   Small segments rejection

-  

-   Repeatidely scan for the smallest segment, and if it is smaller than a 
-   given size, it will be deleted. This is done by splitting it into 2 
-   parts, each part being the one that correlates the most to one the 
-   two neighbor segments. If there is only one neighbor, it is simply 
-   merged into it.

-  

-   The size is given by the user, and shouldn't be greater than the 
-   smallest segment you logically expect from your experiment! 
-   (paradigm, physiology and sampling frequency dependent, at least)

-  

-    See f.ex. before and after a rejection of segments shorter than 
-   3 time frames (the coloring changed between the two):

-  

-   

-  

-   The infamous "Optimal 
-   number of clusters"
and the Meta-Criterion

-  

-   Forewords

-  

-   A point worth mentioning is that we said at the beginning that we were looking for 5 clusters. But actually, we have no a priori 
-   knowledge of how many clusters are right. So we have to run the segmentation 
-   sequentially, and independently, through a range of clusters, for example from 
-   1 to 20 clusters. Each of these segmentations is perfectly valid in itself, 
-   but we wish to have a way to compare between them and select the "optimal one".

-  

-    

-  

-   Many criteria exist, and have been developped based on 
-   different assumptions. However, it is also unfortunate that most of 
-   them are useless for our case. Indeed, a lot of criteria are not 
-   well suited to our type of 
-   data (normalized maps, equivalent to using a cosine distance). And if they 
-   do, they can still give unreliable 
-   results. All in all, on the 20 criteria that have been implemented in Cartool, only a 
-   subset of 9 criteria (since 2024) seem 
-   to be robust enough. But none of them does work accurately in all 
-   cases. So the approach taken in Cartool is to
-   run all of them, and to merge their results into a 
-   compound called the Meta-Criterion.

-  

-    

-  

-   These criteria and meta-criterion were discussed in this article:

-  

-   Bréchet, Brunet, Birot, Gruetter, Michel, Jorge - "Capturing the 
-   spatiotemporal dynamics of self-generated, task-initiated thoughts with EEG 
-   and fMRI" - NeuroImage, July 2019

-  

-   Note 1: the conclusions above are the results of 20+ years of working 
-   on this very specific subject. The selection of the best criteria and the 
-   formula of the Meta-Criterion were both the results of empirical observations, 
-   but, most importantly, of running simulations. These simulations where used 
-   to produce series of quasi-stable micro-states, of random durations, with a 
-   range of 3 to 15 seed maps, each correlated in a range of 10% to 90%, and Gaussian 
-   noise variance ranging from 50 dB to 0 dB (as much noise as data!). Only the criteria surviving these 
-   whole ranges of parameters were kept.

-  

-   The 9 criteria

-  
The best 9 criteria that proved to be the more reliable for our type of 
-  data are:

-  
    
-	  
  1. Dunn, Robust version: An evaluation of the goodness 
-	  of separation of all clusters, with a robust version formula.
    2. 
-	  
  2. Gamma: An adaptation of Goodman and Kruskal, based on 
-	  concordant vs. discordant clustered pairs.
    3. 
-	  
  3. Gamma, second derivative of Robust version: Cartool 
-	  robust version of the Gamma, then using the second derivative.
    4. 
-	  
  4. Krzanowski-Lai Index: A ratio of the relative 
-	  difference of the withinclusters dispersion.
    5. 
-	  
  5. Krzanowski-Lai Index, Cartool version: Cartool 
-	  implementation of the internal second derivative formula.
    6. 
-	  
  6. Point-Biserial: A point-biserial correlation 
-	  calculated between the distance matrix and a binary cluster index.
    7. 
-	  
  7. Point-Biserial, second derivative of Robust version: 
-	  Cartool robust version of the Point-Biserial, then using the second 
-	  derivative.
    8. 
-	  
  8. Silhouettes: Evaluation of the consistency of each 
-	  cluster through its goodness of fit.
    9. 
-	  
  9. Silhouettes second derivative: Second derivative of 
-	  Silhouettes.
    10. 
-  

-  

-    

-  

-   Naming convention for criteria listed in the .error.data files is 
-   the following:

-  
    
-	  
  • <CriterionName>:     
-	  Official criterion taken from literature
    • 
-	  
  • <CriterionName>R:   Robust 
-	  version of criterion
    • 
-	  
  • <CriterionName>'':   Second 
-	  derivative version of criterion
    • 
-	  
  • <CriterionName>R'': Second derivative of
-	  Robust version of criterion
    • 
-	  
  • <CriterionName>C:   Cartool 
-	  own implementation of official formula
    • 
-  

-  

-    

-  

-   For example, current criteria names are: DunnR, 
-   Gamma, GammaR'', KL, KLC,
-   PtBiserial, PtBiserialR'', 
-   Silhouettes and Silhouettes''.

-  

-    

-  

-   Here are the main references for all of these criteria:

-  

-   Charrad, Ghazzali, Boiteau, Niknafs - "NbClust an R package for determining 
-   the relevant number of clusters in a data set" - Journal of Statistical 
-   Software, 2014

Krzanowski, Lai - "A Criterion for Determining the 
-   Number of Groups in a Data Set Using Sum-of-Squares Clustering" - 
-   International Biometric Society, 1988

Milligan, Cooper - "An 
-   examination of procedures for determining the number of clusters in a data 
-   set" - Psychometrika, 1985

-  

-   Note 2: We used to use a Cross-Validation (CV) criterion for a long 
-   time. However, the extensive testing above clearly showed that it was not a 
-   reliable criterion. It was "undershooting" all the 
-   time, having a tendency to report fewer clusters than the real numbers. This 
-   could have induced previous analysis to under-estimate the actual number of 
-   clusters, especially for Resting States analysis. The 
-   CV was therefore removed from our VIP Club of Best Criteria - RIP.

-  

-    

-  

-   Note 3: All criteria have been implemented to have the max value 
-   indicating the optimal clustering. Some criteria work the other way round, 
-   with the min value pointing at the optimal clustering. In these cases, 
-   results were simply inverted to also work with the max value.

-  

-   The Meta-Criterion

-  

-   The meta-criterion is simply defined as the median of all optimal numbers of 
-   clusters across all criteria:

-  
    
-	  
  • Each criterion max position is 1 vote
    • 
-	  
  • The Meta-Criterion is the Median of all votes
    • 
-  

-  

-    

-  

-	  

-  

-    

-  

-   Here is an example of the 9 criteria (top tracks), their
-   geometrical mean, and the 
-   Meta-Criterion (bottom track). The horizontal axis being the number of 
-   clusters, the red squares show the maximum position of a given criterion:

-  

-   

-  

-    

-  

-   Lowest number of clusters

-  

-   The minimum number of clusters that Cartool can return is 
-   actually 4. We are going to detail the reasons why:

-  
    
-	  
  • All (except one) criteria are undefined for 1 cluster. 
-	  Because most of them look at some sorts of separation between clusters, 
-	  there needs to be at least 2 of them to do so.
    • 
-	  
  • Many criteria are also undefined for 2 clusters, too. 
-	  Because they look at differences between some sort of metric across successive 
-	  clustering. As cluster 1's metric does not exist, it can not be used to 
-	  compare with cluster's 2.
    • 
-	  
  • Many criteria will report 3 clusters as being the 
-	  optimal most of the time, which we know is wrong 
-	  from simulated data. The metric computed for 2 clusters shows from 
-	  observation that splitting the dataset into 2 parts is 
-	  really a bad clustering. Then the 
-	  metric computed for 3, 4, 5... clusters show some dramatic improvement. 
-	  But the biggest improvement is between 2 to 3 clusters. If the criteria 
-	  work with some sort of L-corner principle, or with a second-derivative 
-	  formula, then they will be highly biased toward 3 clusters.
    It is 
-	  enough that some criteria will have inaccurate reports for 3 clusters to 
-	  also forbid the use of all the other criteria. Doing otherwise would 
-	  introduce some disbalance 
-	  in the Meta-Criterion voting system.
    • 
-	  
  • Therefore, with our type of data, the minimum possible number of clusters 
-	  is 4.
    • 
-  

-  

-    

-  

-   Note that there are no constraints on the maximum number of clusters, though 
-   (apart to be less or equal to the number of data points). In case of L-corner 
-   or second-derivative criteria, Cartool will silently expand the range of 
-   clusters by 1 or 2 to be able to compute these criteria. But they will not be 
-   part of the output files.

-  

-   Afterwords

-  

-   The optimal number of clusters is a difficult topic. We hope to provide a 
-   more reliable tool with the Meta-Criterion to guide the researcher. By using 
-   different criteria, each being selected for their appropriateness, and 
-   combining them together into a Meta-Criterion, we have a more reliable 
-   estimator of the optimal number of clusters.

-  

-    

-  

-   For Resting States analysis, we recommand the automatic use of the 
-   Meta-Criterion when working in batches at the subject's level, i.e. finding 
-   the optimal number of clusters per subject. Then, on the group level, we 
-   suggest to use the Meta-Criterion more as a guidance, from which you have to 
-   interpret its suggestions. Indeed, it happens the result is really clear-cut, 
-   with a single max position of the Meta-Criterion. Easy case, no needs for 
-   second thoughts. However, other cases can show 2 different local max 
-   positions, suggesting that the data can legitimately be split with either of 
-   these 2 numbers of clusters. In this case, the type of data, the paradigm, or 
-   even experience should guide your final choice.

-  

-   How to run the Segmentation

-  

-   There are two ways to call the segmentation dialog:

-  
    
-   
  • 
-   
    
-    Use the menu Tools
-     | Segmentation of EEG files, and from there select the 
-    files to be segmented together (by Drag & Drop f.ex.)
    
-   
  • 
-   
    
-    Or link together the 
-    files to be segmented, Open 
-    the link, then click on the Segmentation button  (obsolete, 
-	though)
    
-   

-  

-   Then a dialog in 2 parts appears:

-  

-   Segmentation Files Dialog

-  

-   

-    segmentation files dialog

-   

-     

-   

-  

-   
-       
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-       
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-   

-      

-       Files Presets

-      

-       Pick the main type of processing you want to do:
    
-		  
  • ERP segmentation
    • 
-		  
  • Resting States segmentation, on subjects' level
    • 
-		  
  • Resting States segmentation, on group level
    • 
-	  

-		   

-      

-       (1) Segmenting Groups of Files

-      

-       Read some important informations about the meaning
-        of Groups in the Segmentation context.

-      

-       You can use the very convenient Drag & 
-       Drop feature here.

-      

-       Number of groups:

-      

-       A counter of how many groups have been given.

-      

-       Add New Group of Files

-      

-       Enter a new group of file(s).

-      

-       Remove Last Group

-      

-       Does what it says.

-      

-       Clear All Groups

-      

-       Clear out all the groups at once.

-      

-       Read Lists from File

-      

-       You can direclty retrieve the lists of groups previously (see below).

-      

-       See also Drag & Drop.

-      

-       Write Lists to File

-      

-       You can save the lists of current groups into a file, in case you 
-       want to re-use them (much recommended!).

-      

-       See the file formats available.

-      

-       Sort Files within Lists

-      

-       A strange behavior of Windows is to not respect the order of the 
-       files dropped in a window. To help cure this silly habit, you can 
-       sort all the file names of all the groups already entered.

-      

-       (2) Epochs

-      

-       Specify which time period to segment.

-      

-       No Epochs

-      

-       The whole input files will be used for the clustering.

-      

-       List of Epochs:

-      

-       Specify a list of epochs, each epoch being clustered 
-	   independently from the others. In this very case, epochs 
-	   overlapping or not is irrelevant.

-      

-       From

-      

-       From time frame (included)...

-      

-       To

-      

-       ...to time frame (included).

-      

-       Add Epoch

-      

-       Actually inserting the specified epoch to the list. Don't forget to press on this button to enter the current values!

-      

-       If the list remains empty, the segmention process will be run on the 
-       whole dataset.

-      	 

-      

-       Remove Epoch

-      

-       Popping out the last epoch from the list back to the edit fields.

-      

-       Resampled epochs:

-      

-       This will resample your dataset, generating a set of 
-	   epochs from random data points. The intended use is for Resting States.

-       The first time you select this option, Cartool will estimate the 
-	   parameters below. The aim is to statistically cover 95% of your data, but 
-	   you can change that, especially if the number of resampling is too high.

-       See this paragraph about resampling.

-      

-       XX Epochs,

-      

-       The number of random epochs, each epoch being clustered on its own.

-       You can change the number of epochs, and see the corresponding % 
-	   of data coverage in real-time you'll get.

-      

-       of XXXX [TF],

-      

-       The epoch size. This amount of random time points are concatenated into 
-	   each epoch.

-       It might be interesting to you (yes, you) to know that the 
-	   temporal ordering is preserved. Data points, although randoms, appeared 
-	   in the epoch's order.

-       You can change the epoch size, and see the corresponding % of 
-	   data coverage in real-time you'll get.

-      

-       Covering XX% Data

-      

-       Combining the number of epochs by the epoch size, it is possible to 
-	   compute the probability to resample any given time point. Therfore, we 
-	   have an idea of the data coverage.

-       For optimal results, it is of course better to cover most of your data. 
-	   However, if the data were to be totally recurrent, you might ease up this 
-	   number.

-       You can change the % of data coverage, and see the number of 
-	   epochs needed for that in real-time.

-      

-       (3) Files Options

-      

-        

-      

-       Output Base File Name:

-      

-       Specify here a basis for all the file names that will be 
-       generated during the segmentation process.

-      

-       Segment Files (.seg)

-      

-       A visual rendition of the segmentation, which also includes the GEV, GFP, 
-	   and correlation of templates with the data.

-      

-       See the .seg specification.

-      

-       Template Files (.ep)

-      

-       The Templates (or centroids) of the clusters, a weighted avarage of each 
-	   clusters.

-      

-       See the .ep specification.

-      

-       Data per Cluster

-      

-       Original data splitted by clusters.

-	  

-       Currently in .sef format.

-		   

-      

-       Synthetic EEG Files

-      

-       Counterparts of each original file, where the data has been replaced by 
-	   the corresponding template at each time frame, so it is easy to visualize 
-	   the temporal evolution of multiple conditions.

-	  

-       The power of the synthetic maps also follow the power of the original 
-	   data, too.

-	  

-       Currently in .sef format.

-      

-       Resting States:

-      

-       The following options are aimed at improving the Resting States batch 
-	   processing.

-      

-       Force Single Files Processing

-      

-       Each file from each input group will be 
-	   processed individually.

-       So basically, it doesn't care for conditions, and you can Drag&Drop 
-	   all your files at once.

-      

-       Common Best Clustering Directory

-      

-       After each file has been processed, be it the whole subject or some 
-	   resampled epoch, the main results 
-	   are copied to a Best Clustering directory.

-       Files copied are the .error.data, 
-	   the optimal 
-	   templates file, and the corresponding 
-	   verbose .vrb file. 
-	   Directoy name ends is  <base file name>.Best Clustering

-       A useful trick is that you can run multiple Cartools in parallel, 
-	   each with their own subset of subjects. You can then set the exact same 
-	   output base file name in all of them, and select the Common Best 
-	   Clustering Directory. These Cartool instances will therfore write 
-	   concurrently to the same output directory. They will 
-	   not overwrite each others results, though, as file names should be 
-	   unique across subjects. This way you will divide the total processing 
-	   time by the number of Cartool you run...

-      

-       + Delete Individual Directories

-      

-       This option is only available when the previous one is selected.

-       If selected, once the optimal results have been copied to the Common 
-	   Directory, the current file's results will be deleted. At a subject's 
-	   level, we usually don't care for all the non-optimal clustering results. 
-	   As these could amount to a lot of disk space, it is totally OK to dispose 
-	   of them.

-      

-       << Previous  |  Next >>

-      

-       Use these buttons to navigate through the previous and next dialogs 
-       (if any).

-      

-       See which current dialog you are in, and to which other dialogs you 
-       connect, in the tab-like part at the top of the dialog under 
-       the title.

-      	 

-      

-       Process

-      

-       Runs the segmentation.

-      

-       This button remains disabled until all the parameter 
-       dialogs have received enough (and consistent) informations.

-      

-       Cancel

-      

-       Quit the dialog.

-      

-       Help

-      

-       Launch the Help to the right page (should be here...).

-  

-   Segmentation Parameters Dialog

-  

-   segmentation parameters dialog

-  

-    

-   
-       
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-       
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-       
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-       
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-    
-     
-     
-    
-       
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-       
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-   

-      

-       (1) Clustering Parameters

-      

-       Corresponds to Part 1 of the segmentation.

-      

-       Computation Presets:

-      

-       Pick your choice from the drop-down list, according to your data type 
-       and experiment.

-      

-       This will set the input data type 
-       for you (can not be manually changed) and the segmentation parameters 
-       with the most common values (which you can manually tune-up).

-      

-       (1) Data Preprocessing

-      

-       All sorts of preprocessing to tenderize your data before the data 
-	   munching.

-      

-       Spatial Filter, using XYZ file:

-      

-       Applying a Spatial Filter to the 
-	   data, to remove outliers and smooth out the 
-	   noise.

-       K-Means clustering doesn't like noise, lower SNR data in input also leads 
-	   to lower SNR results...

-       However, it is not recommended to apply this filter more than 
-	   once! If your EEG preprocessing pipe-line already included 
-	   the Spatial Filter, you shouldn't use it here! Cartool tries to be 
-	   smart here, if your files contain the characters "Spatial" in their 
-	   names, it will automatically disable this option.

-      

-       Using Whole Data

-      

-       Using all of the data specifed from the
-	   epochs options. So either 
-	   the whole file, some specific time interval, or some resampled epoch. But 
-	   the file given to the clustering will be used as a whole.

-       Mainly used for ERPs analysis.

-      

-       Using only GFP Peaks Data

-      

-       Keeping only the data at local GFP Max positions. These 
-	   are the data points with the higher SNR, and centered on the segments' 
-	   most stable part. Data points with lower GFP are usually transitions due 
-	   to dipoles oscillations, when not at their peak values.

-       This is used only for Resting States analysis.

-       Note that the GFP Max extraction part is done before the 
-	   resampling. All GFP Maxes are first concatenated into a temp 
-	   file, which is then resampled. Resampling disrupt the time line 
-	   consistency, therefore a local GFP Max can not be correctly retrived. 
-	   This also ensures that all the resampled epochs will have the same size.

-      

-       Automatic

-      

-       The GFP track is computed automatically from the input file, then the GFP 
-	   Maxes positions extracted.

-      

-       At Markers:

-      

-       The GFP Maxes might have already been computed, or the user has some 
-	   specific requirements about what data points to keep. With this option, 
-	   you can specify whatever marker names for the time positions to be kept.

-      

-       But Excluding Bad Epochs:

-      

-       Select this option to skip some time periods from your data. 
-	   Data preprocessing is never perfect, and some parts of the data should 
-	   still be ignored.

-       Note that this step is done before the GFP Max and the resampling.

-      

-       Automatic

-      
Cartool has a bad epochs automatic detection (you might want to give it 
-	  a try from the EEG Window, under 
-	  Markers|Scanning Bad Markers menu).

-	  
This option is seen as a last chance before the clustering. It would 
-	  definitely be better to run the detection before, then visually 
-	  assess the bad epochs, then only run the clustering.

-		   

-      

-       At Markers

-      

-       Give the marker names of the bad epochs to be ignored.

-       Either somebody did put some markers manually to isolate the bad epochs, 
-	   or have already run the automatic bad epochs detection.

-      

-       (2) Clustering Parameters

-      

-        

-      

-       Data Type:

-      

-       This is the input data type, set by the Presets list above.

-      

-       Only Positive

-      

-       Data consist of positive only, scalar data. This could be 
-       spikes from neuron recordings, or the Results of Inverse Solution, f.ex.

-      

-       This will logically turn off the Polarity & References options.

-      

-       See this point on 
-       positive data and also this point.

-      

-       Signed

-      

-       Signed scalar values, like, you know, EEG.

-      

-       Vectorial

-      

-       Used on Inverse Solution 
-        .ris data files, 
-       when the results are vectors for each solution points.

-      

-       See this point about segmentation in the 
-       Inverse Solution space.

-      

-       Data reference

-      

-        

-      

-       No Reference

-      

-       Data are used as they come from files, no changes occur.

-      

-       Average Reference

-      

-       Data are average reference-d.

-      

-       Maps / Patterns Polarity:

-      

-        

-      

-       Ignore

-      

-       Polarity of maps does not matter, so ignore it. Inverted maps are 
-       considered the same (same underlying generators, but with reversed polarity).

-      

-       Used for spontaneous EEG recordings.

-      

-       Account

-      

-       Polarity of maps matter, that is, inverted maps are indeed considered 
-       as different.

-      

-       Used for ERPs.
Clustering Method: 

-      

-       K-Means

-      

-       See K-Means clustering. 

-      

-       Number of Random Trials

-      

-       Number of time that the process of randomly picking maps is initiated (steps
-        1 to 4). Of course, higher values increase the chance to 
-       converge to the optimal solution, but at the cost of more processing time.

-      

-       T-AAHC Hierarchical Clustering

-      

-       See Topographic Atomize & Agglomerate 
-       Hierarchical Clustering.

-      

-       Range of Clusters

-      

-        

-      

-       From

-      

-       Minimum number of clusters, keep it to 1.

-      

-       To

-      

-       Maximum number of clusters, usually around 20 for ERPs, and 
-	   12..15 for Resting States.

-       You might want to increase that number if, f.ex., your ERP epoch is 
-	   longer than ~500 ms. Or if the optimal max appears quite close to the 
-	   higher limit. Of course, the higher the maximum number of clusters, the 
-	   longer the processing time.

-       Decreasing this number is a bit more delicate. By doing so you 
-	   might miss the optimal clustering, without any clue about the miss! The 
-	   range suggested by Cartool is based on our experience at the FBMLab, you 
-	   have to have some good reasons to decrease that range.

-      

-       Labeling at Low Correlations:
No Labeling if Below

-      

-       If selected, you can specify a minimum correlation threshold 
-	   for data points to be assigned to a given cluster.

-       Default correlation threshold is set to 50%, which is 
-	   quite conservative.

-       See this outliers rejection paragraph.

-      

-       Alternative Templates:
EEG To Inverse 
-	   / Inverse To EEG

-      

-       This option can help you computing the inverse solution of your 
-	   EEG template maps, or the EEG maps from your inverse 
-	   templates if you run the clustering on
-	   RIS files.

-       There are more explanations here.

-      

-       (3) Temporal Postprocessing

-      

-       Part 2 of the segmentation.

-      

-       Sequentializing Segments

-      

-       Scans the clusters, and split those who belong to the same cluster 
-       but don't overlap in time.

-      

-       Merging Correlated Segments

-      

-       Blindly merge together clusters that are correlated above a threshold.

-       This is quite a harsh post-processing, use with care.

-      

-       If Correlated above:

-      

-       Specify the correlation threshold as a percentage.

-      

-       Segments Temporal Smoothing

-      

-       Redo the labeling, but with a temporal
-        smoothing factor.

-      

-       Window Half Size:

-      

-       The temporal smoothing operates with a sliding window, which you 
-       specify here the half size (in time frames). The actual window size 
-       is therefore ( 2 x W + 1 ).

-      

-       Strength (Besag Factor):

-      

-       Strength  
-       of the smoothing, actually the Besag factor from the article on the 
-       segmentation process.

-      

-       Rejecting Small Segments

-      

-       Deletes short segments, and fuse them with their 2 respective neighbors.

-      

-       Shorter than or equal to:

-      

-       Size below which a segment is removed.

-      

-       << Previous  |  Next >>

-      

-       Use these buttons to navigate through the previous and next dialogs 
-       (if any).

-      

-       See which current dialog you are in, and to which other dialogs you 
-       connect, in the tab-like part at the top of the dialog under 
-       the title.

-      	 

-      

-       Process

-      

-       Runs the segmentation.

-      

-       This button remains disabled until all the parameter 
-       dialogs have received enough (and consistent) informations.

-      

-       Cancel

-      

-       Quit the dialog.

-      

-       Help

-      

-       Launch the Help to the right page (should be here...).

-  

-   Segmentation - Technical points & hints

-  

-   Groups of Files in the Segmentation

-  

-   Each group of files provided in the list will be processed 
-   independently of the other groups. Conversely, all the files 
-   within a group are concurrently segmented together (a 
-   different approach from the Fitting).

-  

-   In this way, we have a sort of batch processing, where you can input 
-   groups with different number of files, and / or different dimensions 
-   (in time, in electrodes). However, the same segmentation
-    parameters will apply for all these segmentations. The 
-   output directories / files will be numbered if more than one group is given.

-  

-   You can Drag & Drop these files 
-   directly from the Explorer:

-  

-   It is strongly recommended to use these Drag & Drop features 
-   which will tremendously ease your work:

-  
-  

-   File formats to save or retrieve the 
-   lists of groups

-  
    
-   
  • 
-   
    
-    .csv file
    
-    
  • .txt text file, with a similar format 
-    as the .csv format above, but separators used are tabs 
-    instead of commas (then rather a .tsv format).
    
-   

-  

-   Maps

-  

-   In all the segmentation and fitting algorithms, normalized maps 
-   are used as only the shape/topology of the maps is of interest, and 
-   not their strengths. The only exception is when generating an average 
-   map to represent a given segment, the original maps are taken to 
-   therefor make a GFP-weighted sum, giving more emphasize to maps with 
-   higher GFP (which are likely to be less noisy and of higher interest).

-  

-   Resampling your data - why should I do that?

-  

-   In the Files Dialog, you can set 
-   some resampling option, aimed at Resting 
-   States processing. Here are the main points why you should favor the 
-   resampling (apart from looking cool, of course):

-  
    
-	  
  • All resampled epochs will have the same size. 
-	  Although files are usually of comparable sizes across subjects or 
-	  conditions, nothing 
-	  guarantees that. And the bigger the file, the less likely the K-Means will 
-	  produce reliable answers. Using the original files, without resampling / 
-	  cropping, could therefore produce results with different levels of 
-	  quality. While equal size epochs should produce comparable quality in 
-	  terms of clusters separation.
    • 
-	  
  • The bigger the file, the more random 
-	  bootstrapping the K-Means will need to ensure a reliable answer. 
-	  This is due to the very random nature of the Lloyd's algorithm. The number of 
-	  trials needed for a correct clustering varies exponentially with the number of data points! 
-	  By using smaller files, for the same amount of random trials, the K-Means 
-	  will produce more reliable clustering.
    • 
-	  
  • Estimating the best optimal 
-	  of clusters is a difficult endeavour. By repeating the analysis of the 
-	  same subjects multiple times, we also reduce our chance of picking the 
-	  wrong number of clusters. Not only due to the repetition process 
-	  itself, 
-	  but also due to the resampled data being slightly different across 
-	  epochs. Stated otherwise, this also allows for resampling of the 
-	  optimal number of clusters.
    • 
-	  
  • Resting States data are supposed to be cyclical, the 
-	  brain looping through some major processes again and again. These 
-	  processes are what the clustering is trying to characterize. 
-	  Resampling cyclical data is perfectly fine and should give the 
-	  same results as a correct, full-size clustering.
    • 
-	  
  • The K-Means algorithm is as a classifier. At its core,
-	  it compares 
-	  maps made of hundreds of electrodes. With 
-	  this amount of dimensions, most of the search space will appear empty, the 
-	  so-called 
-	  cursed of dimensionality. By using the resampling technique, we can
-	  boost the number of data points available at the Group level 
-	  clustering. The increase ratio being roughly the number of 
-	  resampling, which means going from a hundred maps to many thousands is a 
-	  real plus.
    • 
-	  
  • Smaller files analysis will run faster, 
-	  with smaller memory footprint.
    • 
-  

-  

-    

-  

-   TL;DR: Shorter files work better, repeating the K-Means multiple times is 
-   better, using different random parts of the data improves both the K-Means 
-   and the optimal number of clusters.

-  

-    

-  

-   I hope I made a case to use this resampling technique. Resting States 
-   analysis is not an easy task, and the results appear to be much more unstable 
-   than ERPs. This is why we should put more chances on our sides to find the 
-   optimal clustering. You can still ignore it, though, f.ex. if you want to 
-   reproduce some previous results where it was not available.

-  

-   Global Explained Variance computation

-  

-   During the segmentatioin process, the GEV 
-   value is computed across all the provided files, as if they were
-   aggregated into a 
-   single one. It gives a global quality measure of the overall 
-   segmentation process, plus the relative weight/contribution of each segment 
-   into the global segmentation.

-  

-   However, during the fitting process, the GEV is computed on 
-   a set of groups that represent some natural 
-   within-subjects size, which in 
-   turns depend on your paradigm. It can even be computed on a per-file 
-   basis, if subjects were not the same across all groups.

-  

-   This has roughly the same consequence as for GFP 
-   Normalization, in that the denominator part of the 
-   equation will be different 
-   according to the number of files it is computed across. Not 
-   that the absolute sum is of any importance, but rather that individually 
-   scaling each file could introduce some artifacts if some big component was to 
-   be found in one file and not into the others. Which could then make the other 
-   components appear relatively weaker in the other files, thus wrongly 
-   generating significant statistical differences.

-  

-   Outliers rejection

-  

-       By construct, and no matter what, the K-Means clustering will assign 
-	   every data point to one cluster, the one it correlates the most. But 
-	   sometimes, some data points will not correlate well with any of these 
-	   clusters. To avoid degrading the existing clusters with outliers, data 
-	   points whose best correlation are still below a given threshold 
-	   will not be assigned to any cluster.

-       Data points too far from any clusters' cloud will be labeled as 
-	   unclassified. It can also be seen as a hidden, additional 
-	   "garbage" cluster used to gather all of the outliers. Cluster that will 
-	   be subsequently ignored for the remaining computations (centroids,
-	   criteria...).

-       The default correlation threshold is set to 50%, which 
-	   is quite a conservative value. Hence, no more than a few % of the data 
-	   should be classified as unlabeled in the end. Check with the verbose file 
-	   for the amount of unlabeled data, and if too high, then something might 
-	   be wrong with the data. If you increase the threshold, you might end up 
-	   with too much rejection. If you decrease it, you might incorporate 
-	   outliers back to the clusters.

-   Alternative templates

-  

-       (The following explanations are for the regular EEG clustering)

-       Cartool provides an option, the 
-	   "Alternative templates", to compute the corresponding 
-	   localization for each EEG template map.

-       First of all, it expects that all of your input 
-	   EEG files have some RIS files 
-	   counterpart, f.ex. as generated by the RIS 
-	   Computation Toolbox. Cartool expects an exact one-to-one 
-	   match between each EEG and RIS file names (similar file names, 
-	   identical directories). Cartool will complain if some files appear to be 
-	   missing. However it will not whine at all in case no counterpart 
-	   files were found at all, it will just skip this option silently.

-       The clustering will then run as usual at the EEG level, without any 
-	   difference. The final templates are computed as the average of each 
-	   clusters' cloud, as usual. Then, the labeling from the EEG 
-	   clustering will be applied on the alternative dataset, allowing 
-	   to compute the average of the corresponding inverse solutions. 
-	   This way, each EEG template map will have its corresponding inverse 
-	   template.

-        

-       Here is a simplified diagram, showing 18 EEG maps clustered into 3 
-	   groups. Top part shows the results of the regular EEG clustering, with 
-	   the 3 clusters containing each 6 maps, and below them their average maps. 
-	   Bottom part is the alternative dataset, here the inverse space. It is
-	   using the same labeling ("map numbers") to 
-	   compute the average brain activities corresponding to the average EEG 
-	   maps:

-        

-       

-        

-       Note 1: This option is actually working both way. 
-	   If you run the clustering on the RIS data, then the alternative dataset 
-	   will be the EEG maps. The main templates will be brain regions, the 
-	   alternative templates the corresponding EEG maps.

-       Note 2: You can also compute the average inverses through the
-	   Fitting, by saving all data per clusters. Then 
-	   running the RIS Computation Toolbox 
-	   with the proper Preset.

-   Segmentation - Results

-  

-   (See also the Segments display)


-  
    
-      
  • 
-      
    One .error.data 
-	  file which holds a summary of the 
-	  whole range of segmentations, showing the error being made at each 
-	  individual segmentation.
    This file is the most important one (with the 
-	  verbose file) from the overall segmentation, and acts like a dashboard to 
-	  help you decide which segmentation is the most optimal one.
    
-	  
  • 
-      
    One general verbose files <basefilename>.vrb,
-     with all the parameters being used. Keep this precious file with your data, 
-	  this is the only way you can exactly redo your results!
    Then some more 
-	  detailed verbose files <basefilename>.<#clusters>.vrb  
-	  for each number of clusters within the input 
-	  range, with more informations about the clustering results for each 
-	  number of clusters.
    
-   
  • 
-   
    
-    In case of Segment output, some 
-	<basefilename>.<#clusters>.seg 
-    (Segments) files, that can be opened 
-    by Cartool to visually render the results of each individual 
-    segmentation.
    At the first opening, it first displays 
-    the GFP’s of the files 
-    segmented, filled with a color scheme representing the segment 
-    numbers. Scrolling down with the down arrow will cycle through the 
-    Dissimilarity, the segments numbers, the GEV split segment by 
-    segment, and the Correlation between the template map and the map for 
-    each time frame. For example, here is one showing the GFPs:
    
-   
    
-    
    
-   
  • 
-   
    
-    In case of Template output, 
-	<basefilename>.<#clusters>.ep files (or 
-	<basefilename>.<#clusters>.ris 
-    files for inverse space segmentation), containing the template maps 
-	for a given number of clusters. These are the centroids of the  
-	clusters, and each template index correspond to the segment index of the
-	.seg files (above).
    
-   
    
-    
    
-   
  • 
-   
    
-    In case of Data Clusters output, some 
-	<basefilename>.<#clusters>.Cluster<#>.ep files (or .ris 
-    files according to the input files) in the More 
-	directory. Each file holds all the original data splitted by cluster index.
    
-   
  • 
-   
    
-    In case of Synthetic Ouput, some 
-	<basefilename>.<#clusters>.<originalfilename>.ep files (or .ris 
-    files according to the input files) in the More 
-	directory.
    Each time point of the original data is replaced by 
-	its corresponding template map. The original power is then applied 
-	to new time point. This is useful to visually compare the before and after 
-	segmentation.

    Here we can see some original data (top) clustered in 4 
-	groups (colored boxes), and the corresponding synthetic maps (below):
    
-   
    
-    
    
-    
    
-   

-  

-   Segmentation in the Source Space

-  

-   Instead of using EEG data, it is possible to directly segment the
-   Results of Inverse
-    Solution. Instead of the electrical values at each 
-   electrode, it will use the estimated dipoles at each solution 
-   points within the brain.

-  

-   This part has to be totally rewritten due to current evaluations...

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    
+ 
+     

+         

+             Segmentation of EEG Files into Micro-States
+         

+         

+              
+         

+         

+             Segmentation is run first to extract 
+                 template
+                 maps
+             , which can be 
+                 back-fit to the individual
+                 subjects
+              on a second stage.
+         

+         

+              
+         

+         

+             Brief introduction to the segmentation

+             Segmentation of EEG files into micro-states
+         

+         
+         

+             How to run the Segmentation
+         

+         

+             Files Dialog

+             Parameters Dialog
+         

+         

+             Technical points & hints

+             Results

+             Segmentation in the Source Space
+         

+         

+             Brief introduction to the segmentation
+         

+         

+             Segmentation into micro-states is
+             the process of finding periods of stability in the map
+             representation of the ERP's. The data (usually grand means) are then 
+                 segmented
+                 / cut where changes occur
+             , and template maps are computed
+             for each of the resulting segments to
+             act as single representatives of the segments. The segmentation
+             therefore produces:
+         

+         
    
+             
  • 
+                 
    
+                     a labeling for each time
+                     point and for each file, asserting to which segment it belongs to,
    
+             
  • 
+                 a set of template (synthetic) maps that best
+                 represent each segment.
    
+         

+         

+              
+         

+         

+             Given a set of averaged maps, it is possible to fit
+             them back onto individual ERP's:
+         

+         
    
+             
  • 
+                 
    
+                     for each time point, it chooses which map
+                     fits the best, producing again a labeling,
    
+             
  • 
+                 some variables are then extracted from this
+                 "fitting", such as the number of occurrence for each map,
+                 the first occurrence for each map, or when a given map was best
+                 fit. These variables are then used for statistics.
    
+         

+         

+              
+         

+         

+             For the display of the segmentation, see all the 
+                 
+                     Segments
+                     Display
+                 
+             .
+         

+         

+             Segmentation of EEG files into micro-states
+         

+         

+             Methods used for the segmentation
+         

+         

+             It is actually made of three successive steps:
+         

+         
    
+             
  1. 
+                 
    
+                     A mathematical clustering,
    
+             
  2. Some temporal post-processings,
    
+             
  3. Computing some quality measures.
+         

+         

+              
+         

+         

+             Let's introduce briefly these three points:
+         

+         

+             1. Mathematical clustering
+         

+         

+             This is a well-known mathematical process, which does not
+             account for the time dimension of the data. That is, data (maps) are
+             put in a "bag", then picked from there without caring for
+             their actual time stamp. Three methods are available for this stage:
+         

+         
+         

+             2. Temporal post-processings
+         

+         

+             These are optional processings, which have the nice
+             properties, for most of them, to account for the time dimension. They
+             are totally independent of the type of clustering method used in the
+             first stage. The methods available are (in this order):
+         

+         
+         

+             3. Computing clustering quality measures
+         

+         

+             Cartool computes 9 different clustering quality criteria (as
+             of 2024), and then combine them into a meta-criterion. This
+             meta-criterion has a statistically more robust behavior, i.e. it outperforms
+             each individual single criteria alone for correctly guessing the optimal
+             number of clusters.
+         

+         

+             See the full 
+                 discussion about clustering
+                 criteria
+             .
+         

+         

+              
+         

+         

+             Next, we are going to delve into the details of these three stages.
+         

+         

+             Mathematical clustering
+         

+         

+             The K-Means clustering
+         

+         

+             We summarize here the K-Means algorithm as it is used for the EEG
+             data in Cartool. For the sake of clarity, we use practical numbers,
+             by searching for 5 clusters out of 4 conditions of 100 time frames.
+             Time is not relevant in this algorithm, so the total of 400 maps
+             are just "put into a bag".
+         

+         

+              
+         

+         
    
+             
  1. 
+                 
    
+                     Initialization
+                 
    
+                 
      
+                     
    • 
+                         
      
+                             Of the templates: randomly pick 5
+                             non-identical maps out of the 400 data maps.
+                         
      
+                     
    • 
+                         
      
+                             Of the labeling: test each of the 400
+                             maps, and label (index) to which of the 5 templates they correlate
+                             the most.
+                         
      
+                 
    
+             
  2. 
+                 
    
+                     Convergence loop
+                 
    
+                 
      
+                     
    • 
+                         
      
+                             Compute new templates: average all the maps that have the same label.
+                         
      
+                     
    • 
+                         
      
+                             Compute new labeling: test each of the 400 maps, and label
+                             (index) to which of the 5 new templates they correlate the most.
+                         
      
+                     
    • 
+                         
      
+                             Compute a measure of quality of the current labeling (
+                                 Global
+                                 Explained Variance, GEV)
+                             .
+                         
      
+                 
    
+             
  3. 
+                 
    
+                     Repeat step 2, until the GEV doesn't improve anymore.
+                 
    
+             
  4. 
+                 
    
+                     If the end results has a higher GEV than the current best one, keep
+                     it as the current best.
+                 
    
+             
  5. 
+                 
    
+                     Repeat again steps 1 to 4, until enough repetitions have been done.
+                 
    
+         

+         

+              
+         

+         

+             At the end, we have an estimate of the theoretically best segmentation.
+         

+         

+             As there is a random stage in this algorithm, we can only get close
+             to the perfect solution. Also, running again the whole stuff will
+             give slightly different results for the same reason. However, the
+             process is reliable and is a standard procedure. See more 
+                 technical
+                 points
+              here.
+         

+         

+             The Atomize & Agglomerate
+             Hierarchical Clustering (AAHC)
+         

+         

+             Important note: the AAHC is not used anymore in Cartool, only
+             its modified version T-AAHC is available.
+             However, the T-AAHC being based on the AAHC, the explanations below
+             still hold.
+         

+         

+              
+         

+         

+             The usual 
+                 Hierarchical
+                 Agglomerative Clustering
+              is a bottom-up approach. It starts with
+             all maps being a cluster, then it merges the two closest clusters (of
+             the current remaining ones) into a new one, repeatively. In this way,
+             we have all the segmentations from the number of Time Frames down to 1.
+         

+         

+             Cartool implements a modified version of the Hierarchical
+             clustering, specifically tailored for the EEG case, called the 
+                 Atomize
+                 & Agglomerate Hierarchical Clustering (AAHC)
+             .
+         

+         

+             It behaves the same as a regular hierarchical agglomerative
+             clustering, starting with every map being a cluster. Then the main
+             idea is to pick the "worst" segment of all currently
+             availables, to atomize it (split it into indivividual maps), and to
+             re-distribute these maps to the segments they fit most. This also
+             results in all the segmentations from the number of Time Frames
+             downto 1.
+         

+         

+              
+         

+         
    
+             
  1. 
+                 
    
+                     Initialization
+                 
    
+                 
      
+                     
    • 
+                         
      
+                             Of the templates: each map is a template, starting therefore with 400 clusters.
+                         
      
+                     
    • 
+                         
      
+                             Of the labeling: each map labels itself.
+                         
      
+                 
    
+             
  2. 
+                 
    
+                     Removing one cluster
+                 
    
+                 
      
+                     
    • 
+                         
      
+                             Pick the worst cluster: the one with the lowest 
+                                 GEV
+                                 (Global Explained Variance)
+                             .
+                         
      
+                     
    • 
+                         
      
+                             Atomize & distribute: take each map of this cluster, and
+                             assign it to the remaining cluster it correlates the best.
+                         
      
+                     
    • 
+                         
      
+                             Compute new labeling: test each of the 400 maps, and label
+                             (index) to which of the remaining templates they correlate the most.
+                         
      
+                 
    
+             
  3. 
+                 
    
+                     Repeat step 2, removing one cluster at a time, until we reach 5 clusters.
+                 
    
+         

+         

+              
+         

+         

+             The main advantages of this method over the regular Hierarchical
+             Agglomerative Clustering are:
+         

+         
    
+             
  • 
+                 
    
+                     It redefines the boundaries at each step, allowing 
+                         small segments
+                         to remain
+                     .
    
+             
  • 
+                 It gives a far better GEV on each segmentation,
+                 leading to a better choice of the 
+                     optimum
+                     segmentation
+                 .
    
+         

+         

+             There are many advantages of this method over the K-Means:
+         

+         
    
+             
  • 
+                 
    
+                     It gives always the same results, if run again.
    
+             
  • It runs much faster.
    
+             
  • 
+                 It spends its "segmentation power" into
+                 higher GFP areas, then giving the interesting segments earlier.
    
+         

+         

+              
+         

+         

+             A final word could be: try both segmentations, and see the
+             differences by yourself, it's not good to trust blindly (even
+             Cartool). Actually, if there is something in your data, it will show
+             up with both methods anyway!
+         

+         

+              
+         

+         

+             See f.ex. a AAHC versus a K-Means for 18 segments
+             (though it could be hard to compare directly):
+         

+         

+             

+             
+         

+         

+             The Topographic Atomize & Agglomerate
+             Hierarchical Clustering (T-AAHC)
+         

+         

+             The T-AAHC is actually a further refinement of the above AAHC. The
+             main difference being that the 
+                 T-AAHC does not account for the
+                 powers of the maps, but only for their topographies
+             , as the
+             K-Means was doing.
+         

+         

+             Though the power of maps can be significantly used in many cases,
+             there are other cases where they are not. If a given brain area is
+             activated with only a low power, still, this is an interesting event
+             to consider. Or if you want to re-segment a bunch of template maps
+             merged together, they all have the same GFP so power is of no help in
+             this case.
+         

+         

+             The T-AAHC takes the best of both the K-Means, by working only
+             topographies, and the AAHC, by being deterministic and fast,
+             without their respective drawbacks.
+         

+         

+              
+         

+         

+             There is actually only one technical difference between the T-AAHC
+             and the AAHC. At one point, both methods have to pick "the worst
+             cluster" before atomizing it and re-distributing its parts to
+             the other clusters:
+         

+         
    
+             
  • 
+                 
    
+                     The AAHC picks the cluster with the lowest GEV (Global
+                     Explained Variance), in which the GFP of course comes into account.
+                 
    
+             
  • 
+                 
    
+                     The T-AAHC picks the "less explained" cluster, the
+                     one whose maps correlate the worse to its template (cluster with the
+                     lowest sum of correlation).
+                 
    
+         

+         

+              
+         

+         

+             The T-AAHC results are very close to the K-Means ones, see here an
+             example for 15 segments (first one is the T-AAHC, second one is the K-Means):
+         

+         

+             

+             
+         

+         

+             Temporal post-processings
+         

+         

+             Temporal smoothing
+         

+         

+             This was the historical way to remove small segments. We kept it
+             here, but we do prefer the Small maps rejection
+             procedure instead, because its actual behavior is difficult to
+             predict (very parameter dependent).
+         

+         

+             (You can refresh your memory with all the 
+                 formulas
+                 here
+             )
+         

+         

+             In the labeling process, when assigning a map 
+             for each time point t, a distance d is computed, and
+             the map with the lowest distance d chosen:

+             

+             To express the idea that micro-states tend to stay stables, we
+             introduce a smoothing factor in the distance d, by defining a
+             new distance d' that has to minimized the same way:

+             

+             with Nbkt being the number of maps k in the
+             interval t-b to t+b (excluding time t itself),
+             and >0
+             being a weighting factor to control the smoothness. 
+             equal to 0 gives d' = d, while greater values will
+             allow more smoothness. b is a window size, before and after
+             current time point t.
+         

+         

+              
+         

+         

+              See f.ex. before and after a smoothing (Window half size of 3,
+             strength of 10). Note that not all small segments have been removed:
+         

+         

+             
+         

+         

+             Sequentialization
+         

+         

+             The mathematical clustering, as already explained,
+             does not account for the time dimension. It therefore happens very
+             often that maps attributed to a given 
+                 cluster be in fact spread
+                 into very distinct time windows
+             . See for example here cluster 3,
+             or cluster 4:
+         

+         

+             
+         

+         

+              
+         

+         

+             The clustering did a good job grouping maps together, as the best
+             trade-off for 8 clusters. But based on physiological evidences,
+             segments sharing the same label but being 
+                 temporaly
+                 disconnected do not reflect the same neuronal activity
+             . We are
+             then untitled to sequentialize those parts, i.e. to split the
+             clusters with many non-overlapping windows into some sub-clusters.
+         

+         

+              
+         

+         

+             The second generation of the sequentialization process works this way:
+         

+         
    
+             
  • 
+                 
    
+                     For each cluster index:
+                 
    
+                 
      
+                     
    • 
+                         
      
+                             If there is at most one part of that cluster for each file, do
+                             nothing and continue to the next cluster.
+                         
      
+                     
    • 
+                         
      
+                             "Cumulate vertically" all files for that cluster, to get a
+                             labeling telling for each time frame if that cluster has been found
+                             in at least one of the files.
+                         
      
+                     
    • 
+                         
      
+                             Use this labeling to split the cluster into its timely disconnected parts.
+                         
      
+                 
    
+         

+         

+              
+         

+         

+             See here the original clustering without sequentialization (above),
+             then with sequentialization (below). Worth of interest is the
+             splitting of old cluster 1 into new 1 and 9, old cluster 6 into new 7
+             and 11, old cluster 7 into new 13, 15 and 16. Also note that old
+             cluster 8 remains unchanged (though renamed 14) due to the fact that
+             all its parts overlap:
+         

+         

+             

+             
+         

+         

+              
+         

+         

+             Merging correlated maps
+         

+         

+             This procedure blindy merges together all maps that are correlated
+             above a specified threshold. To be used when you really want to force
+             (and only when) the merging of some segments together.
+         

+         

+             Not to be confused with the re-merge step of the Sequentialization.
+             This is another, and independent, processing.
+         

+         

+              
+         

+         

+             See f.ex. before and after merging maps above a correlation of 0.92:
+         

+         

+             

+             
+         

+         

+             Small segments rejection
+         

+         

+             Repeatidely scan for the smallest segment, and if it is smaller than a
+             given size, it will be deleted. This is done by splitting it into 2
+             parts, each part being the one that correlates the most to one the
+             two neighbor segments. If there is only one neighbor, it is simply
+             merged into it.
+         

+         

+             The size is given by the user, and shouldn't be greater than the
+             smallest segment you logically expect from your experiment!
+             (paradigm, physiology and sampling frequency dependent, at least)
+         

+         

+              See f.ex. before and after a rejection of segments shorter than
+             3 time frames (the coloring changed between the two):
+         

+         

+             
+         

+         

+             The infamous "Optimal
+             number of clusters"
and the Meta-Criterion
+         

+         

+             Forewords
+         

+         

+             A point worth mentioning is that we said at the beginning that we were looking for 5 clusters. But actually, we have no a priori
+             knowledge of how many clusters are right. So we have to run the segmentation
+             sequentially, and independently, through a range of clusters, for example from
+             1 to 20 clusters. Each of these segmentations is perfectly valid in itself,
+             but we wish to have a way to compare between them and select the "optimal one".
+         

+         

+              
+         

+         

+             Many criteria exist, and have been developped based on
+             different assumptions. However, it is also unfortunate that 
+                 most of
+                 them are useless
+              for our case. Indeed, a lot of criteria are not
+             well suited to our type of
+             data (normalized maps, equivalent to using a cosine distance). And if they
+             do, they can still give unreliable
+             results. All in all, on the 20 criteria that have been implemented in Cartool, only a
+             subset of 
+                 9 criteria (since 2024) seem
+                 to be robust enough
+             . But none of them does work accurately in all
+             cases. So the approach taken in Cartool is to
+             run all of them, and to 
+                 merge their results into a
+                 compound called the Meta-Criterion
+             .
+         

+         

+              
+         

+         

+             These criteria and meta-criterion were discussed in this article:
+         

+         

+             Bréchet, Brunet, Birot, Gruetter, Michel, Jorge - "Capturing the
+             spatiotemporal dynamics of self-generated, task-initiated thoughts with EEG
+             and fMRI" - NeuroImage, July 2019
+         

+         

+             Note 1: the conclusions above are the results of 20+ years of working
+             on this very specific subject. The selection of the best criteria and the
+             formula of the Meta-Criterion were both the results of empirical observations,
+             but, most importantly, of running simulations. These simulations where used
+             to produce series of quasi-stable micro-states, of random durations, with a
+             range of 3 to 15 seed maps, each correlated in a range of 10% to 90%, and Gaussian
+             noise variance ranging from 50 dB to 0 dB (as much noise as data!). Only the criteria surviving these
+             whole ranges of parameters were kept.
+         

+         

+             The 9 criteria
+         

+         

+             The best 9 criteria that proved to be the more reliable for our type of
+             data are:
+         

+         
    
+             
  1. 
+                 Dunn, Robust version: An evaluation of the goodness
+                 of separation of all clusters, with a robust version formula.
+             
    2. 
+             
  2. 
+                 Gamma: An adaptation of Goodman and Kruskal, based on
+                 concordant vs. discordant clustered pairs.
+             
    3. 
+             
  3. 
+                 Gamma, second derivative of Robust version: Cartool
+                 robust version of the Gamma, then using the second derivative.
+             
    4. 
+             
  4. 
+                 Krzanowski-Lai Index: A ratio of the relative
+                 difference of the withinclusters dispersion.
+             
    5. 
+             
  5. 
+                 Krzanowski-Lai Index, Cartool version: Cartool
+                 implementation of the internal second derivative formula.
+             
    6. 
+             
  6. 
+                 Point-Biserial: A point-biserial correlation
+                 calculated between the distance matrix and a binary cluster index.
+             
    7. 
+             
  7. 
+                 Point-Biserial, second derivative of Robust version:
+                 Cartool robust version of the Point-Biserial, then using the second
+                 derivative.
+             
    8. 
+             
  8. 
+                 Silhouettes: Evaluation of the consistency of each
+                 cluster through its goodness of fit.
+             
    9. 
+             
  9. 
+                 Silhouettes second derivative: Second derivative of
+                 Silhouettes.
+             
    10. 
+         

+         

+              
+         

+         

+             Naming convention for criteria listed in the .error.data files is
+             the following:
+         

+         
    
+             
  • 
+                 <CriterionName>:    
+                 Official criterion taken from literature
+             
    • 
+             
  • 
+                 <CriterionName>R:   Robust
+                 version of criterion
+             
    • 
+             
  • 
+                 <CriterionName>'':   Second
+                 derivative version of criterion
+             
    • 
+             
  • 
+                 <CriterionName>R'': Second derivative of
+                 Robust version of criterion
+             
    • 
+             
  • 
+                 <CriterionName>C:   Cartool
+                 own implementation of official formula
+             
    • 
+         

+         

+              
+         

+         

+             For example, current criteria names are: DunnR, 
+                 Gamma
+             , GammaR'', KL, KLC,
+             PtBiserial, PtBiserialR'', 
+                 Silhouettes
+              and Silhouettes''.
+         

+         

+              
+         

+         

+             Here are the main references for all of these criteria:
+         

+         

+             Charrad, Ghazzali, Boiteau, Niknafs - "NbClust an R package for determining
+             the relevant number of clusters in a data set" - 
+                 Journal of Statistical
+                 Software
+             , 2014

Krzanowski, Lai - "A Criterion for Determining the
+             Number of Groups in a Data Set Using Sum-of-Squares Clustering" - 
+                 International Biometric Society
+             , 1988

Milligan, Cooper - "An
+             examination of procedures for determining the number of clusters in a data
+             set" - Psychometrika, 1985
+         

+         

+             Note 2: We used to use a Cross-Validation (CV) criterion for a long
+             time. However, the extensive testing above clearly showed that it was not a
+             reliable criterion. It was "undershooting" all the
+             time, having a tendency to report fewer clusters than the real numbers. This
+             could have induced previous analysis to under-estimate the actual number of
+             clusters, especially for Resting States analysis. The
+             CV was therefore removed from our VIP Club of Best Criteria - RIP.
+         

+         

+              
+         

+         

+             Note 3: All criteria have been implemented to have the max value
+             indicating the optimal clustering. Some criteria work the other way round,
+             with the min value pointing at the optimal clustering. In these cases,
+             results were simply inverted to also work with the max value.
+         

+         

+             The Meta-Criterion
+         

+         

+             The meta-criterion is simply defined as the 
+                 median of all optimal numbers of
+                 clusters across all criteria
+             :
+         

+         
    
+             
  • Each criterion max position is 1 vote
    • 
+             
  • The Meta-Criterion is the Median of all votes
    • 
+         

+         

+              
+         

+         

+             
+         

+         

+              
+         

+         

+             Here is an example of the 9 criteria (top tracks), their
+             geometrical mean, and the
+             Meta-Criterion (bottom track). The horizontal axis being the number of
+             clusters, the red squares show the maximum position of a given criterion:
+         

+         

+             
+         

+         

+              
+         

+         

+             Lowest number of clusters
+         

+         

+             The minimum number of clusters that Cartool can return is
+             actually 4. We are going to detail the reasons why:
+         

+         
    
+             
  • 
+                 All (except one) criteria are undefined for 1 cluster.
+                 Because most of them look at some sorts of separation between clusters,
+                 there needs to be at least 2 of them to do so.
+             
    • 
+             
  • 
+                 Many criteria are also undefined for 2 clusters, too.
+                 Because they look at differences between some sort of metric across successive
+                 clustering. As cluster 1's metric does not exist, it can not be used to
+                 compare with cluster's 2.
+             
    • 
+             
  • 
+                 Many criteria will report 3 clusters as being the
+                 optimal most of the time, which we know is wrong
+                 from simulated data. The metric computed for 2 clusters shows from
+                 observation that splitting the dataset into 2 parts is 
+                 really a bad clustering. Then the
+                 metric computed for 3, 4, 5... clusters show some dramatic improvement.
+                 But the biggest improvement is between 2 to 3 clusters. If the criteria
+                 work with some sort of L-corner principle, or with a second-derivative
+                 formula, then they will be highly biased toward 3 clusters.
    It is
+                 enough that some criteria will have inaccurate reports for 3 clusters to
+                 also forbid the use of all the other criteria. Doing otherwise would
+                 introduce some disbalance
+                 in the Meta-Criterion voting system.
+             
    • 
+             
  • 
+                 Therefore, with our type of data, 
+                     the minimum possible number of clusters
+                     is 4
+                 .
+             
    • 
+         

+         

+              
+         

+         

+             Note that there are no constraints on the maximum number of clusters, though
+             (apart to be less or equal to the number of data points). In case of L-corner
+             or second-derivative criteria, Cartool will silently expand the range of
+             clusters by 1 or 2 to be able to compute these criteria. But they will not be
+             part of the output files.
+         

+         

+             Afterwords
+         

+         

+             The optimal number of clusters is a difficult topic. We hope to provide a
+             more reliable tool with the Meta-Criterion to guide the researcher. By using
+             different criteria, each being selected for their appropriateness, and
+             combining them together into a Meta-Criterion, we have a more reliable
+             estimator of the optimal number of clusters.
+         

+         

+              
+         

+         

+             For Resting States analysis, we recommand the automatic use of the
+             Meta-Criterion when working in batches at the subject's level, i.e. finding
+             the optimal number of clusters per subject. Then, on the group level, we
+             suggest to use the Meta-Criterion more as a guidance, from which you have to
+             interpret its suggestions. Indeed, it happens the result is really clear-cut,
+             with a single max position of the Meta-Criterion. Easy case, no needs for
+             second thoughts. However, other cases can show 2 different local max
+             positions, suggesting that the data can legitimately be split with either of
+             these 2 numbers of clusters. In this case, the type of data, the paradigm, or
+             even experience should guide your final choice.
+         

+         

+             How to run the Segmentation
+         

+         

+             There are two ways to call the segmentation dialog:
+         

+         
+         

+             Then a dialog in 2 parts appears:
+         

+         

+             Segmentation Files Dialog
+         

+         

+             

+                 segmentation files dialog
+             

+             

+                  
+             

+         

+         

+             
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+             

+                         

+                             Files Presets
+                     

+                         

+                             Pick the main type of processing you want to do:
    
+                                 
  • ERP segmentation
    • 
+                                 
  • Resting States segmentation, on subjects' level
    • 
+                                 
  • Resting States segmentation, on group level
    • 
+                             

+                     

+                         

+                             (1) Segmenting Groups of Files
+                     

+                         

+                             Read some important informations about the 
+                                 meaning
+                                 of Groups
+                              in the Segmentation context.
+                         

+                         

+                             You can use the very convenient 
+                                 Drag &
+                                 Drop feature
+                              here.
+                     

+                         

+                             Number of groups:
+                     

+                         

+                             A counter of how many groups have been given.
+                     

+                         

+                             Add New Group of Files
+                     

+                         

+                             Enter a new group of file(s).
+                     

+                         

+                             Remove Last Group
+                     

+                         

+                             Does what it says.
+                     

+                         

+                             Clear All Groups
+                     

+                         

+                             Clear out all the groups at once.
+                     

+                         

+                             Read Lists from File
+                     

+                         

+                             You can direclty retrieve the lists of groups previously (see below).
+                         

+                         

+                             See also Drag & Drop.
+                     

+                         

+                             Write Lists to File
+                     

+                         

+                             You can save the lists of current groups into a file, in case you
+                             want to re-use them (much recommended!).
+                         

+                         

+                             See the file formats available.
+                     

+                         

+                             Sort Files within Lists
+                     

+                         

+                             A strange behavior of Windows is to not respect the order of the
+                             files dropped in a window. To help cure this silly habit, you can
+                             sort all the file names of all the groups already entered.
+                     

+                         

+                             (2) Epochs
+                     

+                         

+                             Specify which time period to segment.
+                     

+                         

+                             No Epochs
+                     

+                         

+                             The whole input files will be used for the clustering.
+                     

+                         

+                             List of Epochs:
+                     

+                         

+                             Specify a list of epochs, 
+                                 each epoch being clustered
+                                 independently from the others
+                             . In this very case, epochs
+                             overlapping or not is irrelevant.
+                     

+                         

+                             From
+                     

+                         

+                             From time frame (included)...
+                     

+                         

+                             To
+                     

+                         

+                             ...to time frame (included).
+                     

+                         

+                             Add Epoch
+                     

+                         

+                             Actually inserting the specified epoch to the list. Don't forget to press on this button to enter the current values!
+                         

+                         

+                             If the list remains empty, the segmention process will be run on the
+                             whole dataset.
+                         

+                     

+                         

+                             Remove Epoch
+                     

+                         

+                             Popping out the last epoch from the list back to the edit fields.
+                     

+                         

+                             Resampled epochs:
+                     

+                         

+                             This will resample your dataset, generating a set of
+                             epochs from random data points. The intended use is for Resting States.
+                         

+                             The first time you select this option, Cartool will estimate the
+                             parameters below. The aim is to statistically cover 95% of your data, but
+                             you can change that, especially if the number of resampling is too high.
+                         

+                             See this paragraph about resampling.
+                     

+                         

+                             XX Epochs,
+                     

+                         

+                             The number of random epochs, each epoch being clustered on its own.
+                         

+                             
+                                 You can change the number of epochs, and see the corresponding %
+                                 of data coverage in real-time you'll get.
+                             
+                     

+                         

+                             of XXXX [TF],
+                     

+                         

+                             The epoch size. This amount of random time points are concatenated into
+                             each epoch.
+                         

+                             It might be interesting to you (yes, you) to know that the
+                             temporal ordering is preserved. Data points, although randoms, appeared
+                             in the epoch's order.
+                         

+                             
+                                 You can change the epoch size, and see the corresponding % of
+                                 data coverage in real-time you'll get.
+                             
+                     

+                         

+                             Covering XX% Data
+                     

+                         

+                             Combining the number of epochs by the epoch size, it is possible to
+                             compute the probability to resample any given time point. Therfore, we
+                             have an idea of the data coverage.
+                         

+                             For optimal results, it is of course better to cover most of your data.
+                             However, if the data were to be totally recurrent, you might ease up this
+                             number.
+                         

+                             
+                                 You can change the % of data coverage, and see the number of
+                                 epochs needed for that in real-time.
+                             
+                     

+                         

+                             (3) Files Options
+                     

+                         

+                              
+                     

+                         

+                             Output Base File Name:
+                     

+                         

+                             Specify here a basis for all the file names that will be
+                             generated during the segmentation process.
+                     

+                         

+                             Segment Files (.seg)
+                     

+                         

+                             A visual rendition of the segmentation, which also includes the GEV, GFP,
+                             and correlation of templates with the data.
+                         

+                         

+                             See the .seg specification.
+                     

+                         

+                             Template Files (.ep)
+                     

+                         

+                             The Templates (or centroids) of the clusters, a weighted avarage of each
+                             clusters.
+                         

+                         

+                             See the .ep specification.
+                     

+                         

+                             Data per Cluster
+                     

+                         

+                             Original data splitted by clusters.
+                         

+                         

+                             Currently in .sef format.
+                         

+                     

+                         

+                             Synthetic EEG Files
+                     

+                         

+                             Counterparts of each original file, where the data has been replaced by
+                             the corresponding template at each time frame, so it is easy to visualize
+                             the temporal evolution of multiple conditions.
+                         

+                         

+                             The power of the synthetic maps also follow the power of the original
+                             data, too.
+                         

+                         

+                             Currently in .sef format.
+                     

+                         

+                             Resting States:
+                     

+                         

+                             The following options are aimed at improving the Resting States batch
+                             processing.
+                     

+                         

+                             Force Single Files Processing
+                     

+                         

+                             Each file from each input group 
+                                 will be
+                                 processed individually
+                             .
+                         

+                             So basically, it doesn't care for conditions, and you can Drag&Drop
+                             all your files at once.
+                     

+                         

+                             Common Best Clustering Directory
+                     

+                         

+                             After each file has been processed, be it the whole subject or some
+                             resampled epoch, the main results
+                                 are copied to a Best Clustering directory
+                             .
+                         

+                             Files copied are the .error.data,
+                             the optimal 
+                                 templates file
+                             , and the corresponding
+                             verbose .vrb file.
+                             Directoy name ends is  <base file name>.Best Clustering
+                         

+                             A useful trick is that you can run multiple Cartools in parallel,
+                             each with their own subset of subjects. You can then set the exact same
+                             output base file name in all of them, and select the Common Best
+                             Clustering Directory. These Cartool instances will therfore write
+                             concurrently to the same output directory. They will 
+                                 not overwrite
+                              each others results, though, as file names should be
+                             unique across subjects. This way you will divide the total processing
+                             time by the number of Cartool you run...
+                     

+                         

+                             + Delete Individual Directories
+                     

+                         

+                             This option is only available when the previous one is selected.
+                         

+                             If selected, once the optimal results have been copied to the Common
+                             Directory, the current file's results will be deleted. At a subject's
+                             level, we usually don't care for all the non-optimal clustering results.
+                             As these could amount to a lot of disk space, it is totally OK to dispose
+                             of them.
+                     

+                         

+                             << Previous  |  Next >>
+                     

+                         

+                             Use these buttons to navigate through the previous and next dialogs
+                             (if any).
+                         

+                         

+                             See which current dialog you are in, and to which other dialogs you
+                             connect, in the tab-like part at the top of the dialog under
+                             the title.
+                         

+                     

+                         

+                             Process
+                     

+                         

+                             Runs the segmentation.
+                         

+                         

+                             This button remains 
+                                 disabled until all the parameter
+                                 dialogs have received enough (and consistent) informations
+                             .
+                     

+                         

+                             Cancel
+                     

+                         

+                             Quit the dialog.
+                     

+                         

+                             Help
+                     

+                         

+                             Launch the Help to the right page (should be here...).
+                     

+         

+         

+             Segmentation Parameters Dialog
+         

+         

+             segmentation parameters dialog
+         

+         

+              
+         

+         
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+         

+                     

+                         (1) Clustering Parameters
+                 

+                     

+                         Corresponds to Part 1 of the segmentation.
+                 

+                     

+                         Computation Presets:
+                 

+                     

+                         Pick your choice from the drop-down list, according to your data type
+                         and experiment.
+                     

+                     

+                         This will set the input data type
+                         for you (can not be manually changed) and the segmentation parameters
+                         with the most common values (which you can manually tune-up).
+                 

+                     

+                         (1) Data Preprocessing
+                 

+                     

+                         All sorts of preprocessing to tenderize your data before the data
+                         munching.
+                 

+                     

+                         Spatial Filter, using XYZ file:
+                 

+                     

+                         Applying a Spatial Filter to the
+                         data, to remove outliers and 
+                             smooth out the
+                             noise
+                         .
+                     

+                         K-Means clustering doesn't like noise, lower SNR data in input also leads
+                         to lower SNR results...
+                     

+                         However, it is not recommended to apply this filter more than
+                         once! 
+                             If your EEG preprocessing pipe-line already included
+                             the Spatial Filter, you shouldn't use it here!
+                          Cartool tries to be
+                         smart here, if your files contain the characters "Spatial" in their
+                         names, it will automatically disable this option.
+                 

+                     

+                         Using Whole Data
+                 

+                     

+                         Using all of the data specifed from the
+                         epochs options. So either
+                         the whole file, some specific time interval, or some resampled epoch. But
+                         the file given to the clustering will be used as a whole.
+                     

+                         Mainly used for ERPs analysis.
+                 

+                     

+                         Using only GFP Peaks Data
+                 

+                     

+                         Keeping only the data at local GFP Max positions. These
+                         are the data points with the higher SNR, and centered on the segments'
+                         most stable part. Data points with lower GFP are usually transitions due
+                         to dipoles oscillations, when not at their peak values.
+                     

+                         This is used only for Resting States analysis.
+                     

+                         Note that 
+                             the GFP Max extraction part is done before the
+                             resampling
+                         . All GFP Maxes are first concatenated into a temp
+                         file, which is then resampled. Resampling disrupt the time line
+                         consistency, therefore a local GFP Max can not be correctly retrived.
+                         This also ensures that all the resampled epochs will have the same size.
+                 

+                     

+                         Automatic
+                 

+                     

+                         The GFP track is computed automatically from the input file, then the GFP
+                         Maxes positions extracted.
+                 

+                     

+                         At Markers:
+                 

+                     

+                         The GFP Maxes might have already been computed, or the user has some
+                         specific requirements about what data points to keep. With this option,
+                         you can specify whatever marker names for the time positions to be kept.
+                 

+                     

+                         But Excluding Bad Epochs:
+                 

+                     

+                         Select this option to skip some time periods from your data.
+                         Data preprocessing is never perfect, and some parts of the data should
+                         still be ignored.
+                     

+                         Note that this step is done before the GFP Max and the resampling.
+                 

+                     

+                         Automatic
+                 

+                     

+                         Cartool has a bad epochs automatic detection (you might want to give it
+                         a try from the EEG Window, under 
+                             Markers|Scanning Bad Markers
+                          menu).
+                     

+                     

+                         This option is seen as a last chance before the clustering. It would
+                         definitely be better to run the detection before, then visually
+                         assess the bad epochs, then only run the clustering.
+                     

+                 

+                     

+                         At Markers
+                 

+                     

+                         Give the marker names of the bad epochs to be ignored.
+                     

+                         Either somebody did put some markers manually to isolate the bad epochs,
+                         or have already run the automatic bad epochs detection.
+                 

+                     

+                         (2) Clustering Parameters
+                 

+                     

+                          
+                 

+                     

+                         Data Type:
+                 

+                     

+                         This is the input data type, set by the Presets list above.
+                 

+                     

+                         Only Positive
+                 

+                     

+                         Data consist of positive only, scalar data. This could be
+                         spikes from neuron recordings, or the Results of Inverse Solution, f.ex.
+                     

+                     

+                         This will logically turn off the Polarity & References options.
+                     

+                     

+                         See this 
+                             point on
+                             positive data
+                          and also this point.
+                 

+                     

+                         Signed
+                 

+                     

+                         Signed scalar values, like, you know, EEG.
+                 

+                     

+                         Vectorial
+                 

+                     

+                         Used on Inverse Solution 
+                         .ris data files,
+                         when the results are vectors for each solution points.
+                     

+                     

+                         See this point about 
+                             segmentation in the
+                             Inverse Solution space
+                         .
+                 

+                     

+                         Data reference
+                 

+                     

+                          
+                 

+                     

+                         No Reference
+                 

+                     

+                         Data are used as they come from files, no changes occur.
+                 

+                     

+                         Average Reference
+                 

+                     

+                         Data are average reference-d.
+                 

+                     

+                         Maps / Patterns Polarity:
+                 

+                     

+                          
+                 

+                     

+                         Ignore
+                 

+                     

+                         Polarity of maps does not matter, so ignore it. Inverted maps are
+                         considered the same (same underlying generators, but with reversed polarity).
+                     

+                     

+                         Used for spontaneous EEG recordings.
+                 

+                     

+                         Account
+                 

+                     

+                         Polarity of maps matter, that is, inverted maps are indeed considered
+                         as different.
+                     

+                     

+                         Used for ERPs.
+                 
Clustering Method: 

+                     

+                         K-Means
+                 

+                     

+                         See K-Means clustering. 
+                 

+                     

+                         Number of Random Trials
+                 

+                     

+                         Number of time that the process of randomly picking maps is initiated (
+                             steps
+                             1 to 4
+                         ). Of course, higher values increase the chance to
+                         converge to the optimal solution, but at the cost of more processing time.
+                 

+                     

+                         T-AAHC Hierarchical Clustering
+                 

+                     

+                         See 
+                             Topographic Atomize & Agglomerate
+                             Hierarchical Clustering
+                         .
+                 

+                     

+                         Range of Clusters
+                 

+                     

+                          
+                 

+                     

+                         From
+                 

+                     

+                         Minimum number of clusters, keep it to 1.
+                 

+                     

+                         To
+                 

+                     

+                         Maximum number of clusters, usually around 20 for ERPs, and
+                         12..15 for Resting States.
+                     

+                         You might want to increase that number if, f.ex., your ERP epoch is
+                         longer than ~500 ms. Or if the optimal max appears quite close to the
+                         higher limit. Of course, the higher the maximum number of clusters, the
+                         longer the processing time.
+                     

+                         Decreasing this number is a bit more delicate. By doing so you
+                         might miss the optimal clustering, without any clue about the miss! The
+                         range suggested by Cartool is based on our experience at the FBMLab, you
+                         have to have some good reasons to decrease that range.
+                 

+                     

+                         Labeling at Low Correlations:
No Labeling if Below
+                 

+                     

+                         If selected, you can specify a minimum correlation threshold
+                         for data points to be assigned to a given cluster.
+                     

+                         Default correlation threshold is set to 50%, which is
+                         quite conservative.
+                     

+                         See this outliers rejection paragraph.
+                 

+                     

+                         Alternative Templates:
EEG To Inverse
+                         / Inverse To EEG
+                 

+                     

+                         This option can help you 
+                             computing the inverse solution of your
+                             EEG template maps
+                         , or the 
+                             EEG maps from your inverse
+                             templates
+                          if you run the clustering on
+                         RIS files.
+                     

+                         There are more explanations here.
+                 

+                     

+                         (3) Temporal Postprocessing
+                 

+                     

+                         Part 2 of the segmentation.
+                 

+                     

+                         Sequentializing Segments
+                 

+                     

+                         Scans the clusters, and split those who belong to the same cluster
+                         but don't overlap in time.
+                 

+                     

+                         Merging Correlated Segments
+                 

+                     

+                         Blindly merge together clusters that are correlated above a threshold.
+                     

+                         This is quite a harsh post-processing, use with care.
+                 

+                     

+                         If Correlated above:
+                 

+                     

+                         Specify the correlation threshold as a percentage.
+                 

+                     

+                         Segments Temporal Smoothing
+                 

+                     

+                         Redo the labeling, but with a 
+                             temporal
+                             smoothing factor
+                         .
+                 

+                     

+                         Window Half Size:
+                 

+                     

+                         The temporal smoothing operates with a sliding window, which you
+                         specify here the half size (in time frames). The actual window size
+                         is therefore ( 2 x W + 1 ).
+                 

+                     

+                         Strength (Besag Factor):
+                 

+                     

+                         Strength 
+                         of the smoothing, actually the Besag factor from the article on the
+                         segmentation process.
+                 

+                     

+                         Rejecting Small Segments
+                 

+                     

+                         Deletes short segments, and fuse them with their 2 respective neighbors.
+                 

+                     

+                         Shorter than or equal to:
+                 

+                     

+                         Size below which a segment is removed.
+                 

+                     

+                         << Previous  |  Next >>
+                 

+                     

+                         Use these buttons to navigate through the previous and next dialogs
+                         (if any).
+                     

+                     

+                         See which current dialog you are in, and to which other dialogs you
+                         connect, in the tab-like part at the top of the dialog under
+                         the title.
+                     

+                 

+                     

+                         Process
+                 

+                     

+                         Runs the segmentation.
+                     

+                     

+                         This button remains 
+                             disabled until all the parameter
+                             dialogs have received enough (and consistent) informations
+                         .
+                 

+                     

+                         Cancel
+                 

+                     

+                         Quit the dialog.
+                 

+                     

+                         Help
+                 

+                     

+                         Launch the Help to the right page (should be here...).
+                 

+         

+             Segmentation - Technical points & hints
+         

+         

+             Groups of Files in the Segmentation
+         

+         

+             Each group of files provided in the list will be 
+                 processed
+                 independently of the other groups
+             . Conversely, all the files
+             within a group are concurrently segmented together (a
+             different approach from the Fitting).
+         

+         

+             In this way, we have a sort of batch processing, where you can input
+             groups with different number of files, and / or different dimensions
+             (in time, in electrodes). However, the same 
+                 
+                     segmentation
+                     parameters
+                 
+              will apply for all these segmentations. The
+             output directories / files will be numbered if more than one group is given.
+         

+         

+             You can Drag & Drop these files
+             directly from the Explorer:
+         

+         

+             It is strongly recommended to use these Drag & Drop features
+             which will tremendously ease your work:
+         

+         
+         

+             File formats to save or retrieve the
+             lists of groups
+         

+         
    
+             
  • 
+                 
    
+                     .csv file
    
+             
  • 
+                 .txt text file, with a similar format
+                 as the .csv format above, but separators used are tabs
+                 instead of commas (then rather a .tsv format).
    
+         

+         

+             Maps
+         

+         

+             In all the segmentation and fitting algorithms, normalized maps
+             are used as only the shape/topology of the maps is of interest, and
+             not their strengths. The only exception is when generating an average
+             map to represent a given segment, the original maps are taken to
+             therefor make a GFP-weighted sum, giving more emphasize to maps with
+             higher GFP (which are likely to be less noisy and of higher interest).
+         

+         

+             Resampling your data - why should I do that?
+         

+         

+             In the Files Dialog, you can set
+             some resampling option, aimed at Resting
+             States processing. Here are the main points 
+                 why you should favor the
+                 resampling
+              (apart from looking cool, of course):
+         

+         
    
+             
  • 
+                 All resampled epochs will have the same size.
+                 Although files are usually of comparable sizes across subjects or
+                 conditions, nothing
+                 guarantees that. And the bigger the file, the less likely the K-Means will
+                 produce reliable answers. Using the original files, without resampling /
+                 cropping, could therefore produce results with different levels of
+                 quality. While equal size epochs should produce comparable quality in
+                 terms of clusters separation.
+             
    • 
+             
  • 
+                 
+                     The bigger the file, the more random
+                     bootstrapping the K-Means will need
+                  to ensure a reliable answer.
+                 This is due to the very random nature of the Lloyd's algorithm. The number of
+                 trials needed for a correct clustering varies exponentially with the number of data points!
+                 By using smaller files, for the same amount of random trials, the K-Means
+                 will produce more reliable clustering.
+             
    • 
+             
  • 
+                 
+                     Estimating the best optimal
+                     of clusters
+                  is a difficult endeavour. By repeating the analysis of the
+                 same subjects multiple times, 
+                     we also reduce our chance of picking the
+                     wrong number of clusters
+                 . Not only due to the repetition process
+                 itself,
+                 but also due to the resampled data being slightly different across
+                 epochs. Stated otherwise, this also allows for 
+                     resampling of the
+                     optimal number of clusters
+                 .
+             
    • 
+             
  • 
+                 Resting States data are supposed to be cyclical, the
+                 brain looping through some major processes again and again. These
+                 processes are what the clustering is trying to characterize. 
+                     Resampling cyclical data is perfectly fine
+                  and should give the
+                 same results as a correct, full-size clustering.
+             
    • 
+             
  • 
+                 The K-Means algorithm is as a classifier. At its core,
+                 
+                     it compares
+                     maps made of hundreds of electrodes
+                 . With
+                 this amount of dimensions, most of the search space will appear empty, the
+                 so-called 
+                     cursed of dimensionality
+                 . By using the resampling technique, we can
+                 
+                     boost the number of data points available at the Group level
+                     clustering
+                 . The increase ratio being roughly the number of
+                 resampling, which means going from a hundred maps to many thousands is a
+                 real plus.
+             
    • 
+             
  • 
+                 Smaller files analysis will run faster,
+                 with smaller memory footprint.
+             
    • 
+         

+         

+              
+         

+         

+             TL;DR: Shorter files work better, repeating the K-Means multiple times is
+             better, using different random parts of the data improves both the K-Means
+             and the optimal number of clusters.
+         

+         

+              
+         

+         

+             I hope I made a case to use this resampling technique. Resting States
+             analysis is not an easy task, and the results appear to be much more unstable
+             than ERPs. This is why we should put more chances on our sides to find the
+             optimal clustering. You can still ignore it, though, f.ex. if you want to
+             reproduce some previous results where it was not available.
+         

+         

+             Global Explained Variance computation
+         

+         

+             During the segmentatioin process, the GEV
+             value is computed across all the provided files, as if they were
+             
+                 aggregated into a
+                 single one
+             . It gives a global quality measure of the overall
+             segmentation process, plus the relative weight/contribution of each segment
+             into the global segmentation.
+         

+         

+             However, during the fitting process, the GEV is computed on
+             a set of groups that represent some natural 
+                 within-subjects size
+             , which in
+             turns depend on your paradigm. It can even be computed on a 
+                 per-file
+                 basis
+             , if subjects were not the same across all groups.
+         

+         

+             This has roughly the same consequence as for 
+                 GFP
+                 Normalization
+             , in that the denominator part of the 
+             equation will be different
+             according to the number of files it is computed across. Not
+             that the absolute sum is of any importance, but rather that individually
+             scaling each file could introduce some artifacts if some big component was to
+             be found in one file and not into the others. Which could then make the other
+             components appear relatively weaker in the other files, thus wrongly
+             generating significant statistical differences.
+         

+         

+             Outliers rejection
+         

+         

+             By construct, and no matter what, the K-Means clustering will assign
+             every data point to one cluster, the one it correlates the most. But
+             sometimes, some data points will not correlate well with any of these
+             clusters. To avoid degrading the existing clusters with outliers, data
+             points whose best 
+                 correlation are still below a given threshold
+                 will not be assigned to any cluster
+             .
+         

+             Data points too far from any clusters' cloud will be 
+                 labeled as
+                 unclassified
+             . It can also be seen as a hidden, additional
+             "garbage" cluster used to gather all of the outliers. Cluster that will
+             be subsequently ignored for the remaining computations (centroids,
+             criteria...).
+         

+             The default correlation threshold is set to 50%, which
+             is quite a conservative value. Hence, no more than a few % of the data
+             should be classified as unlabeled in the end. Check with the verbose file
+             for the amount of unlabeled data, and if too high, then something might
+             be wrong with the data. If you increase the threshold, you might end up
+             with too much rejection. If you decrease it, you might incorporate
+             outliers back to the clusters.

+                 Alternative templates
+             

+         

+             (The following explanations are for the regular EEG clustering)
+         

+             Cartool provides an option, the 
+                 
+                     "Alternative templates"
+                 
+             , to compute the corresponding
+             localization for each EEG template map.
+         

+             First of all, it expects that all of your input
+             EEG files have some RIS files
+             counterpart, f.ex. as generated by the 
+                 RIS
+                 Computation Toolbox
+             . Cartool expects an 
+                 exact one-to-one
+                 match between each EEG and RIS file names
+              (similar file names,
+             identical directories). Cartool will complain if some files appear to be
+             missing. However it will not whine at all in case 
+                 no counterpart
+                 files were found at all
+             , it will just skip this option silently.
+         

+             The clustering will then run as usual at the EEG level, without any
+             difference. The final templates are computed as the average of each
+             clusters' cloud, as usual. Then, the 
+                 labeling from the EEG
+                 clustering will be applied on the alternative dataset
+             , allowing
+             to compute the average of the corresponding inverse solutions.
+             This way, each EEG template map will have its corresponding inverse
+             template.
+         

+              
+         

+             Here is a simplified diagram, showing 18 EEG maps clustered into 3
+             groups. Top part shows the results of the regular EEG clustering, with
+             the 3 clusters containing each 6 maps, and below them their average maps.
+             Bottom part is the alternative dataset, here the inverse space. It is
+             using the same labeling ("map numbers") 
+                 to
+                 compute the average brain activities corresponding to the average EEG
+                 maps
+             :
+         

+              
+         

+             
+         

+              
+         

+             Note 1: This option is actually working both way.
+             If you run the clustering on the RIS data, then the alternative dataset
+             will be the EEG maps. The main templates will be brain regions, the
+             alternative templates the corresponding EEG maps.
+         

+             Note 2: You can also compute the average inverses through the
+             Fitting, by saving all data per clusters. Then
+             running the RIS Computation Toolbox
+             with the proper Preset.

+                 Segmentation - Results
+             

+         

+             (See also the Segments display)


+         

+         
    
+             
  • 
+                 
    
+                     One .error.data
+                     file which holds a 
+                         summary of the
+                         whole range of segmentations
+                     , showing the error being made at each
+                     individual segmentation.
    This file is the most important one (with the
+                     verbose file) from the overall segmentation, and acts like a dashboard to
+                     help you decide which segmentation is the most optimal one.
+                 
    
+             
  • 
+                 
    
+                     One general verbose files <basefilename>.vrb,
+                     with all the parameters being used. Keep this precious file with your data,
+                     this is the only way you can exactly redo your results!
    Then some more
+                     detailed verbose files <basefilename>.<#clusters>.vrb 
+                     for each number of clusters within the 
+                         input
+                         range
+                     , with more informations about the clustering results for each
+                     number of clusters.
+                 
    
+             
  • 
+                 
    
+                     In case of Segment output, some 
+                         
+                             <basefilename>.<#clusters>
+                         .seg
+                     
+                     (Segments) files, that can be 
+                         opened
+                         by Cartool
+                      to visually render the results of each individual
+                     segmentation.
    At the first opening, it first displays
+                     the GFP’s of the files
+                     segmented, filled with a color scheme representing the segment
+                     numbers. Scrolling down with the down arrow will cycle through the
+                     Dissimilarity, the segments numbers, the GEV split segment by
+                     segment, and the Correlation between the template map and the map for
+                     each time frame. For example, here is one showing the GFPs:
+                 
    
+                 
    
+                     
+                 
    
+             
  • 
+                 
    
+                     In case of Template output, 
+                         
+                             <basefilename>.<#clusters>
+                         .ep
+                      files (or
+                     <basefilename>.<#clusters>.ris
+                     files for inverse space segmentation), containing the template maps
+                     for a given number of clusters. These are the centroids of the 
+                     clusters, and each template index correspond to the segment index of the
+                     .seg files (above).
+                 
    
+                 
    
+                     
+                 
    
+             
  • 
+                 
    
+                     In case of Data Clusters output, some 
+                         <basefilename>.<#clusters>.Cluster<#>.ep
+                      files (or .ris
+                     files according to the input files) in the More
+                     directory. Each file holds all the original data splitted by cluster index.
+                 
    
+             
  • 
+                 
    
+                     In case of Synthetic Ouput, some 
+                         
+                             <basefilename>.<#clusters>.<originalfilename>
+                         .ep
+                      files (or .ris
+                     files according to the input files) in the More
+                     directory.
    Each time point of the 
+                         original data is replaced by
+                         its corresponding template map
+                     . The original power is then applied
+                     to new time point. This is useful to visually compare the before and after
+                     segmentation.

    Here we can see some original data (top) clustered in 4
+                     groups (colored boxes), and the corresponding synthetic maps (below):
+                 
    
+                 
    
+                     
    
+                     
+                 
    
+         

+         

+             Segmentation in the Source Space
+         

+         

+             Instead of using EEG data, it is possible to directly segment the
+             
+                 Results of Inverse
+                 Solution
+             . Instead of the electrical values at each
+             electrode, it will use the estimated dipoles at each solution
+             points within the brain.
+         

+         

+             This part has to be totally rewritten due to current evaluations...
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+     

  
 
\ No newline at end of file
diff --git a/docs/ReferenceGuide/mri-display.html b/docs/ReferenceGuide/mri-display.html
index 2535f0b1..00b9d7cf 100644
--- a/docs/ReferenceGuide/mri-display.html
+++ b/docs/ReferenceGuide/mri-display.html
@@ -15,995 +15,1364 @@
 }
 
  
- 
-  

-   MRIs and Volumes Display

-  

-   Buttons

-  

-      

-  

-     

-  

-   

-  

-      

-  

-    

-  

-      

-  

-   Mouse

-  

-   Changing Isosurface value

-  

-   Keyboard

-  

-   Menus

-  

-   Filters menu
Options menu

-  
-  

-   Technical points

-  

-   Initial background threshold value

-   Guessing what the volume actually is

-   Searching for the orientation

-   'Depth shifting' trick
Talairach coordinates in MRI

-  

-   MRI - Buttons

-  

-   Rendering  

-  

-   Toggles between 4 display modes (see here for basic 
-   explanations on rendering):

-  
    
-   
  • 
-   
    
-    Up to three orthogonal, transparent
-     slices (useful when superimposed on another volume!):
    
-   
    
-    
    
-   
    
-    If the Volume has been detected as 
-    the results of some computations, transparency is inversely 
-    proportional to the intensity. Otherwise, transparency is constant.
    
-   
  • 
-   
    
-    Up to three orthogonal, opaque slices:
    
-   
    
-    
    
-   
    
-    You can select which planes you want to see 
-    or hide, and move them with the mouse.
-     Brightness and contrast 
-    can be adjusted.
    
-   
  • 
-   
    
-    Transparent isosurface:
    
-   
    
-    
    
-   
    
-    The surface is transparently drawn, so you can link
-     other windows into it, and see through its surface.
    
-   
  • 
-   
    
-    Opaque isosurface:
    
-   
    
-    
    
-   
    
-    The surface is drawn opaque, which will hide any other contained linked
-     windows. In this case use the previous renderings (or the 
-    infamous "Depth-shift trick" for 
-    the inner window).
    
-   

-  

-   Change the Isosurface cutting value  

-  

-   Dynamically adjust the isosurface 
-   cutting value (or background threshold value).
-    By holding the mouse's right button 
-   down, moving upward increases the isosurface cutting value 
-   (therefor "shrinking" the volume appearance), and the 
-   opposite when moving downward.

-  

-   During this process, only a low resolution version of the 
-   volume is displayed, to gain speed. Only when releasing the button 
-   the full resolution isosurface will be computed, and displayed. You 
-   can have a short time lag before the final isosurface appears, due to 
-   this computationally expensive process. Also, some geometrical 
-   details hidden in the low resolution display will appear in the 
-   higher resolution. You will get use to it, and you can re-adjust very 
-   quickly by again using the mouse, or with the options
-    menu.

-  

-   For those interested in technical details, up to 6 volumes are cached 
-   by the isosurface functions. The first access to the isosurface will 
-   copy the volume, then filters it, and later calls will only use this 
-   cache, again, for an overall gain in speed.

-  

-   Colorize the exterior surface  

-  

-   Usually, the exterior surface of a volume appears with a predefined 
-   exterior color (kind of shiny, silver-like). When activating this 
-   button, you can assign a color of your choice to the exterior surface.
-    This can be helpful to discriminate between different volumes (or 
-   just because you like colors).

-  

-   The colors at your disposal are the ones in the current Color
-    Table, so you may have to change it to have the right colors. 
-   The exterior surface actually "has a value" set to the 
-   current Isosurface cutting value, so its 
-   color is the one picked in the color table with this value. This 
-   means that changing the Isosurface cutting value will also change the 
-   color (no headache, this is intuitive). Also, changing  the Brightness
-    level (or the Contrast level) will also 
-   affect the color chosen, and this is rather the way to go.

-  

-    

-  

-   Here is an example, with the same Isosurface cut, first without the 
-   colorization, then with colorization and with two different brighness levels:

-  

-   

-  

-   And another example with the same brightness level, but with 
-   increased Isosurface cutting values:

-  

-   

-  

-   And finally, if a volume has been detected
-    as a ROI volume, many exterior colors are used, one for each 
-   underlying ROI values:

-  

-   

-  

-   Editing / cutting into the volume  

-  

-   You have here a set of tools (currently 5) to help you edit / cut / remove 
-   some unwanted parts of the current volume:

-  
    
-	  
  • Deleting a centered sphere
    • 
-	  
  • Blurring within a centered sphere
    • 
-	  
  • Deleting a cylinder perpendicular to surface
    • 
-	  
  • Deleting a sphere perpendicular to surface
    • 
-	  
  • Deleting below a plane perpendicular to surface
    • 
-  

-  

-    

-  

-   You switch between these tools by repeatedly pressing on the cutting 
-   button. And you quit the editing mode after the last tool, or after 
-   pressing the Esc key.

-  

-   Every tool will graphically display itself as some sort of reddish, 
-   semi-transparent object. The tool will adapt itself in real 
-   time to the current position your pointing at.

-  

-   There will also be some hint showing up at the bottom of the display, 
-   to remind you in which editing mode you currently are.

-  

-   Finally, simply Middle-clicking with the mouse will apply the 
-   tool at your current position, deleting all data inside.

-  

-   Deleting Centered Sphere

-  

-   A reddish sphere appears:

-  
    
-	  
  • centered under the current mouse position
    • 
-	  
  • its radius can be adjusted with a right-click
-     + moving left-right
    • 
-  

-  

-    

-  

-   Useful to delete big floating blobs, or clipping some round regions in the 
-   volume: 

-  

-   

-  

-   Blurring Centered Sphere

-  

-   3 concentric reddish spheres appear:

-  
    
-	  
  • centered under the current mouse position
    • 
-	  
  • their radiuses can be adjusted with a right-click
-     + moving left-right
    • 
-	  
  • The inner sphere shows where the maximum blurring 
-	  will occur.
    No blurring will be applied past the outer sphere.
    
-	  The in-between sphere shows the half-blurring limit.
    • 
-  

-  

-    

-  

-   Very useful to anonymize a full head, so that the individual's face could not 
-   be recognizable anymore. You might have to apply the filter a few times to 
-   achieve the desired level of blurriness, while changing location a bit while 
-   doing so. And of course, work on a copy of the original head!

-  

-   Note that the internal parts of the MRI get also blurred, 
-   and not only the face, which might also affect the brain itself. So don't 
-   attempt to extract the brain on the blurred head, the latter is 
-   merely for display and not other processing!

-  

-   

-  

-   Deleting Cylinder perpendicular to surface

-  

-   A reddish cylinder appears:

-  
    
-	  
  • centered under the current mouse position
    • 
-	  
  • its radius can be adjusted with a right-click
-     + moving left-right
    • 
-	  
  • its length can be adjusted with a right-click
-     + moving up-down
    • 
-	  
  • its direction is the local gradient 
-	  ("perpendicular" to data)
    • 
-  

-  

-    

-  

-   This is useful to punch all sorts of holes that are not spherically shaped:

-  

-   

-  

-   Deleting Sphere perpendicular to surface

-  

-   A reddish sphere appears:

-  
    
-	  
  • it is tangent to the current surface it touches, 
-	  always pointing outwardly
    • 
-	  
  • its radius can be adjusted with a right-click
-     + moving left-right
    • 
-	  
  • it uses the local gradient ("perpendicular" to data) 
-	  to point "outside"
    • 
-  

-  

-    

-  

-   This sphere differs from the first one by how it lands on the data. First one 
-   is centered on the position you point. While this one simply touches the 
-   surface of the volume. This is useful to delete stuff floating outside 
-   of an object of interest (which will remain intact):

-  

-   

-  

-   Deleting below plane perpendicular to surface

-  

-   A reddish plane appears, shown as a big disk:

-  
    
-	  
  • centered under the current mouse position
    • 
-	  
  • its normal is the local gradient ("perpendicular" to 
-	  data)
    • 
-	  
  • it might be necessary to zoom out the object to have a better view of 
-	  the cutting plane whereabout
    • 
-  

-  

-    

-  

-   This will cut all data on the one side of the plane shown by the gradient 
-   vector:

-  

-   

-  

-   Other hints

-  
    
-      
  • 
-      
    
-    The cutting tools are all fully in 3D, you might need to rotate your 
-	  object at hand to get the right view and the right shot!
    
-	  
  • 
-      
    
-      If you use some clipping plane, then you can 
-	  totally cut inside the volume...
    
-	  
  • 
-      
    
-      Before you begin, make and use a copy of the volume you want to edit, so as to 
-    not alter the original file!
    
-   
  • 
-   
    
-    Save file often, every time when you are fine with the current results. 
-	Then you can use the  File | Revert  
-	to undo the last operation!
    
-   
  • 
-   
    
-    All operations incorporate some kind of anti-aliasing, so 
-	that the resulting cuts look natural.
    However this does not 
-	apply to masks, which are rather cut "sharply". This is to prevent 
-	creating new intermediate values, a definitive no-no for
-	masks or ROIs.
    
-   

-  

-   Clipping plane Coronal  

-  

-   Select a Coronal clipping ("cutting") plane (see below).

-  

-   Clipping plane Transverse  

-  

-   Select a Transverse clipping ("cutting") plane (see below).

-  

-   Clipping plane Sagittal  

-  

-   Select a Sagittal clipping ("cutting") plane.

-  

-    

-  

-   If in the slice rendering modes, 
-   it simply toggles the planes on or off:

-  

-   

-  

-   If in the volume rendering modes, it 
-   cuts the volume, showing one half first, then the second half,
-    and then off again:

-  

-   

-  

-   In the case above the clippping planes can also be cumulated, 
-   then only the intersection of the 2 or 3 planes are clipped (note 
-   that it will become more computationally demanding):

-  

-   

-  

-   All in all, you have 8 clipping combinations, 2 in each axis, 
-   allowing to clip any octant.

-  

-   See also the related topic of searching 
-   and displaying the orientation.

-  

-   Slice mode  

-  

-   You switch to a serie of 2D slices:

-  

-   

-   By pressing many times on the button, you have access to coronal, 
-   transverse and sagittal displays.

-  

-   The previous 3D display is still used (and might be modified 
-   as well), following the last slice, as to give an idea of  where 
-   the slices are actually cutting.

-  

-   You can still rotate 
-   the slices, if the orientation does not fit your taste.

-  

-   More or less slices  

-  

-   While keeping the first and last slices position fixed, this will 
-   either add or remove intermediate slices. If pressing the Shift 
-   key at the same time, it either add all the slices between the 
-   current extremes, or remove all slices at once.

-  

-   Move first slice  

-  

-   Move the first slice forward or backward, the meaning of it being 
-   dependent of what is the current slice mode (coronal, transverse or 
-   sagittal). If pressing the Shift key at the same time, it will 
-   step faster each time.

-  

-   Move last slice  

-  

-   Move the last slice forward or backward, the meaning of it being 
-   dependent of what is the current slice mode (coronal, transverse or 
-   sagittal). If pressing the Shift key at the same time, it will 
-   step faster each time.

-  

-   Show Max  

-  

-   Draws a symbol at the maximum position, which can be either:

-  
    
-   
  • 
-   
    
-    A transparent circle, always on top of the display / 
-    volume, even if the max itself is not directly in sight:
    
-   
    
-    
    
-   
  • 
-   
    
-    A solid 3D cross, visible only if the perspective 
-    allows it:
    
-   
    
-    
    
-   

-  

-   The slices are not automatically positionned at the max. If 
-   you want to do that use the Find Max 
-   position button (below).

-  

-   Find Max position  

-  

-   This will position the current cutting plane(s) at the maximum position.

-  

-   It will not automatically show where the max is on the 
-   cutting plane, though. To that aim, use the Show
-    Max button (above).

-  

-    

-  

-   Here the max is shown as a 3D cross, and 
-   the Find Max position is not activated (top pictures), then 
-   activated (bottom pictures):

-  

-   

-  

-   

-  

-    

-  

-   Brightness  

-  

-   Only when you have some clipping planes 
-   active, it changes the brightness of the slices displayed. It also 
-   works in the special case of isosurface
-    coloring.

-  

-   Technically, there is a mapping from values to colors, and increasing 
-   the brightness decreases the maximum value (indicated above the color 
-   scale) mapped to the maximum color, therefor making lower values 
-   appear brighter:

-  

-   

-  

-   Contrast  

-  

-   Contrast does not change the maximum value mapped to the maximum 
-   color, but changes the slope of the mapping, increasing or 
-   decreasing the color differences between low and high values.

-  

-   Low contrast is achieved through a linear mapping of the values to 
-   the colors. Higher contrasts are done by an exponential mapping (as a 
-   Gamma correction), making low values appear dimmer, and high values 
-   appear brighter:

-  

-   

-  

-   Note in the pictures above, that the maximum mapped value has not 
-   changed. Though the appearance of the color scale (on the right) has 
-   changed, correctly reflecting the non-linear color mapping (more 
-   colors for higher values when increasing contrast).

-  

-   Color auto scaling  

-  

-   Sets the maximum volume value to the maximum color value. Put it 
-   another way: automatically sets the brightness to match and correctly 
-   display the data. Consequently, the brightness 
-   buttons become inactive, but still the contrast 
-   can be adjusted.

-  

-   Color modes  

-  

-   Cycles through different color tables (black to white, white to 
-   black, black to yellow to white, etc...):

-  

-   

-  

-   MRI - Mouse

-  

-   Go here for the mouse actions 
-   common to all views.

-  

-   Changing the Isosurface cutting value

-  

-   While in Isosurface mode, by holding the 
-   mouse's right button down, moving upward will increase 
-   the isosurface cutting value, therefore "shrinking" the 
-   volume. Conversely, moving downward will increase the 
-   isosurface cutting value, "inflating" the volume.

-  

-    

-  

-   The visual hints 
-   associated with the isosurface:

-  

-   

-    

-   

-  

-   MRI - Keyboard

-  

-   See the general 3D keyboard 
-   and basic window keyboard actions.

-  

-   MRI - Menus

-  

-   Filters menu

-  

-   A whole bunch of filters are here for you to play with, enjoy!

-  

-   The filters apply to the current MRI at its current state. Here are 
-   the main families of filters:

-  

-    

-  
    
-   
    
-    Denoising
    
-   
      
-    
      
-     All you need for cleaning up MRIs: Gaussian, Median, Mean...
      
-    
    
-   
    
-    Arithmetic
    
-   
      
-    
      
-     Arithmetic operation like intensity rescaling.
      
-    
    
-   
    
-    Histogram
    
-   
      
-    
      
-     Comuting histograms, Equalization, Compacting equalized histograms.
      
-    
    
-   
    
-    Mask
    
-   
      
-    
      
-     Thresholding, binarization, combining & applying masks, plus a 
-     bunch of operations on the neighborhood density.
      
-    
    
-   
    
-    Morphology
    
-   
      
-    
      
-     Classical Dilate / Erode / Open / Close, plus some more like 
-     Thinning, Waterfall...
      
-    
    
-   
    
-    Partial Derivatives
    
-   
      
-    
      
-     Gradient, Laplacian, Hessian, k Curvature...
      
-    
    
-   
    
-    Statistics
    
-   
      
-    
      
-     Mean, SD, Coefficient of variation, Median, Mode, MAD, IQR, Entropy etc...
      
-    
    
-   
    
-    Brain processing
    
-   
      
-    
      
-     Bias Field Correction
      
-    
      
-     Grey Matter segmentation
      
-    
      
-     White & Grey matter segmentation
      
-    
      
-     Skull stripping
      
-    
    
-   

-  

-   Options menu

-  
    
-   
    
-    Specify another Isosurface thresold value
-    
    
-   
    
-    Specify another Isosurface 
-    downsampling quality
-    
      
-     Big MRI's or volumes (dimensions > 128) have a downsampled 
-     isosurface by default. It does not affect the data displayed on slices,
-      but just the outer look of the surface. Downsampling makes the 
-     surface lighter and faster in memory, at the expense of a loss of 
-     spatial precision. If you want maximum precision (for that nice 
-     snapshot...), change this downsampling to 1 (can eat up to 50 M of 
-     memory!), and on the contrary, if you don't bother, you might 
-     increase it (though not so useful above 2).
      
-    
      
-      
      
-    
    
-   
    
-    Set orientation flags
-    
      
-     Force Cartool to assign an orientation meaning to the X,Y and Z axis, 
-     like X pointing to the Right, Y pointing Anterior, and Z pointing up.
      
-    
    
-   
    
-    Reset orientation flags
-    
      
-     Cancel the orientation specified by the user.
      
-    
    
-   
    
-    Set new Origin
-    
      
-     Set the voxel of origin, i.e. the one that will become coordinates (0,0,0).
      
-    
      
-      
      
-    
    
-   
    
-    Show/hide informations
-    
      
-     Show or hides some summary about the data.
      
-    
    
-   
    
-    Show/hide color scaling
-    
      
-     Does what it says (the color scaling is the thing on the right).
      
-    
    
-   
    
-    Show/hide axis
-    
      
-     Show or hides the X, Y, Z axis.
      
-    
    
-   
    
-    Show/hide orientation
-    
      
-     Toggles on or off the orientation cues (top, bottom, left, right, 
-     front, back) displayed on the sides of the window.
      
-    
    
-   
    
-     
    
-   
    
-    Flip along X axis
-    
      
-     Permute the data along the X axis.
      
-    
    
-   
    
-    Flip along Y axis
-    
      
-     Permute the data along the Y axis.
      
-    
    
-   
    
-    Flip along Z axis
-    
      
-     Permute the data along the Z axis.
      
-    
    
-   
    
-    Flip X and Y axis
-    
      
-     Permute the data along the X and Y axis.
      
-    
    
-   
    
-    Flip Y and Z axis
-    
      
-     Permute the data along the Y and Z axis.
      
-    
    
-   
    
-    Flip X and Z axis
-    
      
-     Permute the data along the X and Z axis.
      
-    
    
-   
    
-     
    
-   
    
-    'Depth shifting' trick (see here 
-    for full explanations)
-    
      
-     Off
-     
        
-      turn it off, back to normal behavior.
        
-     
      
-    
      
-     Light
-     
        
-      allow a depth shift up to 12% of the maximum depth.
        
-     
      
-    
      
-     Medium
-     
        
-      allow a depth shift up to 25% of the maximum depth.
        
-     
      
-    
      
-     High
-     
        
-      allow a depth shift up to 37% of the maximum depth.
        
-     
      
-    
      
-     Maximum
-     
        
-      allow a depth shift up to 50% of the maximum depth (half of the volume).
        
-     
      
-    
    
-   

-  

-   MRI - Technical points

-  

-   Initial background threshold value

-  

-   When opening (or modifying) a volume, it is needed to estimate the 
-   value below which is only noise (or null data), and above which are 
-   significant data. This value is called the background threshold value,
-    and is also used as the inital isosurface 
-   cutting value.

-  

-   Though it seems very intuitive to you when a looking at the data, 
-   remember you are using a very complex image analysis processing 
-   called the human visual system. But when it comes to an automatic 
-   process, things get tougher, so here is the method currently in use:

-  

-   Cartool first computes a downsampled histogram of the volume, then 
-   cuts at the first valley following the first peak. The first peak 
-   usually designates the background voxels values, which are more or 
-   less the most numerous low values voxels. So cutting just after the 
-   peak end usually leads to the best results.

-  

-   Remarks:

-  
    
-   
  • 
-   
    
-    The algorithm also cares for the special case where a volume has been 
-    partially extracted and embeded into another one. This could give 2 
-    low values peaks, one for value 0 (null/empty background), and 
-    another one with the original, noisy background.
    
-    
  • It also behaves nicely (usually) even when values 
-    have been redistributed over the full range of possible values, 
-    modifying the dynamic range of the data, and giving a comb-like histogram.
    
-    
  • Finally, Cartool will restrain the background 
-    threshold value not to exceed 25% of the whole dynamic range of the 
-    data (it is supposed to be a background value).
    
-   

-  

-   Background threshold value can be modified later on, either through 
-   this option, or by the interactive
-    isosurface process.

-  

-   Background threshold value is implicitly used when searching for the orientation,
-    and can therefor affect its proper detection.

-  

-   Guessing what the volume actually is

-  

-   Though not a vital point, Cartool tries to guess what the heck is 
-   that volume you just opened! It has absolutely no influence on the 
-   content itself, and it will not modify anything in it! 
-   However, Cartool uses its guess to tune up a few parameters for a 
-   better display, like the isosurface smoothness, the isosurface 
-   cutting value, the colors, etc...

-  

-    

-  

-   Cartool will "guess" between these different types of volumes:

-  
    
-   
  • 
-   
    
-    A Full Head, that means, an original scan that has not been 
-    (that much) modified. The surface is made "smooth", with 
-    default black-to-white colors:
    
-   

-  

-   

-    

-   

-  
    
-   
  • 
-   
    
-    A Segmented Brain, that is an original scan that has been 
-    clipped to some of its parts (grey matter, white matter, etc...). The 
-    surface is made "smooth", with black-to-white colors:
    
-   

-  

-   

-    

-   

-  
    
-   
  • 
-   
    
-    A Binary Mask, which contains only 2 values (0 and whatever). 
-    The surface is made to look "LEGO-like" as to reflect the 
-    idea of a mask, and with black-to-white colors:
    
-   

-  

-   

-    

-   

-  
    
-   
  • 
-   
    
-    A ROI Mask, which is made of regions with arbitrary fixed 
-    values. The surface is made to look "LEGO-like" as to 
-    reflect the idea of a mask, with an external
-     coloring done from the ROI's values, and with rainbow-ish colors:
    
-   

-  

-   

-    

-   

-  
-  

-  

-  
    
-      
  • 
-      
    
-    A Blob, usually the results of some computations. The surface 
-    is made "not-too-smooth", with rainbow-ish colors:
    
-   

-  

-   

-    

-   

-  
    
-   
  • 
-   
    
-    None of these.
    
-   

-  

-   Searching for the orientation

-  

-   Cartool tries to "understand" by itself the orientation of 
-   the data inside the volume. There are many reasons to do this. 
-   Firstly, there are many formats supported in Cartool, and not all of 
-   them do include informations on how oriented the data are. Secondly, 
-   though some formats have the ability to describe the orientation, it 
-   may not be used, or even worse, may be used erroneously. And finally, 
-   there are people who like to define an orientation system of their 
-   own, and you have to guess which one in the 48 possible systems.

-  

-   So the best solution is simply to ignore all this mess. Cartool will 
-   read a volume as it is written in the file and will not attempt 
-   anything to re-orient it (i.e. coregistration is the user's responsability).
-    However, it will try to guess, as we are dealing with (some sort of) 
-   brains and heads, how it is oriented to simplify and ease the 
-   manipulation and display:

-  

-   

-  
    
-   
  • 
-   
    
-    Flags are displayed on the borders of the window, showing the closest 
-    possible indications for the projected axis.
    
-   
  • 
-   
    
-    Rotating the object will automatically update the flags' positions 
-    and contents (just try it!).
    
-   
  • 
-   
    
-    Using the default orientation button,
-     you can cycle through 6 predefined rotations, consistent for all 
-    volumes (sagittal, coronal and transverse views, on both side).
    
-   
  • 
-   
    
-    You can still turn off the display through this
-     option.
    
-   

-  

-    

-  

-   I will not describe the algorithm used here, as it has not been 
-   published, and is still under development. Enough to say it works by 
-   scanning the volume, sequentially finding axis by looking for 
-   symetries, center of gravity, and a few other appropriate methods. It 
-   has been tested on a lot of volumes, of low and high resolutions, 
-   extracted brains or full heads, partially cut or complete, MRIs or 
-   PETs, etc... But still the result may be incorrect if there are 
-   unwanted artifacts in the volume. In any case, it will not modify nor 
-   interfere with the real data.

-  

-   The success of the detection will depend on the initial background
-    threshold value, so an incorrect threshold is very likely to 
-   give an incorrect orientation. Cartool also waits for something like
-    a brain, so if the volume is not looking close to this (say, 
-   your grandfather's watch), the result is simply unpredictable (though 
-   sometimes it works!). If the detection totally fails, the flags are 
-   simply "X Max", "X Min", "Y Max" etc...

-  

-   'Depth shifting' trick

-  

-   In the real world, an object and its image are (without entering in a 
-   metaphysical discussion) at the same place. So you can touch what you 
-   see, except for holograms, right?

-   Now with computers, you can do more un-natural tricky things. In the 
-   present case, we can introduce a shift between the depth position 
-   of the "object" (where it is), and its image (where 
-   we see it). So it will appear rather normally, though its position is 
-   actually displaced toward the viewer (you / the screen). 
-   Intuitively, we will see the object contained into another one, 
-   displayed "on top" of it instead of being occluded. See an 
-   example with 3 increasing depth shifts:

-  

-   

-  

-   Though the full head is opaque, and the brain is inside (well, 
-   usually...), with increasing the depth shift we can visualize up to 
-   the half of the brain (the maximum) seen on top of the head. But this
-    is not by any mean a "projection onto the surface" of the head.

-  

-   The depth shift is limited to up to the half of the object, therefor 
-   hiding its furthest half in all cases (in the example above, we will 
-   never see the left hemisphere of the brain, as we see from the right side).

-  

-    

-  

-   Very important notice:

-  

-   Once a shift has been introduced, you could easily induce a 
-   misinterpretation of where the data really are while rotating the 
-   volume. I therefor strongly recommend to use it very cautiously,
-    and to favor orthogonal simultaneous views only.

-   See an example of possible misinterpretation due to small rotations, 
-   the inner blob is nearly central but can be made as if it were on the 
-   left or on the right side:

-  

-   

-  

-   Talairach coordinates in MRI

-  

-   Talairach coordinates are, at the moment, hardwired into the code and 
-   therefor available only for a restricted set of MRI files: the 
-   MNI / McGill standard brains.

-  

-   The files which Cartool recognizes can only be the following:
    *MNI152T1*.hdr
    MNI152.Nlin*.hdr
            
    avg152T1_smac_brain.hdr
    avg152T1_smac_grey.hdr
    avg152T1_smac_pro.hdr
    avg152T1_smac_pro_grid.3005p.spi
            
    ave152_sym_brain.hdr
    ave152_sym_grey.hdr
    ave152_sym_pro.hdr
    ave152_sym_pro_grid.2738p.spi
            
    avg152T1.fld

-    

-  

-   Only then are these functionalities available:

-  

-    

-  
    
-   
  • 
-   
    
-    Tools | Geometry transform 
-    (set of points) , from the general menu:
    
-   
    
-    Give one (or more) text file(s), which each line contains a set of 
-    3D coordinates in the original MRI space. Each of these 3D 
-    coordinates will be transformed to Talairach, and outputed in a new 
-    file. F.ex.:
    
-   
    
-     
    
-    59.877 64.004 31.437   will become    
-    -6.4474739e+01 -1.2306906e+01  1.7800585e+01
    
-   
    
-     
    
-   
    
-    Note that you can run the Talairach Daemon on this new output file, 
-    to get the corresponding brain areas.
    
-   
    
-     
    
-   
  • 
-   
    
-    You can poll with the mouse 
-    in the volume, and get the Talairach coordinates of the clicked 
-    location, in real-time:
    
-   
    
-    
    
-   

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    
+ 
+     

+         

+             MRIs and Volumes Display
+         

+         

+             Buttons
+         

+         

+                
+         

+         

+               
+         

+         

+             
+         

+         

+                
+         

+         

+              
+         

+         

+                
+         

+         

+             Mouse
+         

+         

+             Changing Isosurface value
+         

+         

+             Keyboard
+         

+         

+             Menus
+         

+         

+             Filters menu
Options menu
+         

+         
+         

+             Technical points
+         

+         

+             Initial background threshold value

+             Guessing what the volume actually is

+             Searching for the orientation

+             'Depth shifting' trick
Talairach coordinates in MRI
+         

+         

+             MRI - Buttons
+         

+         

+             Rendering  
+         

+         

+             Toggles between 4 display modes (see here for basic
+             explanations on rendering):
+         

+         
    
+             
  • 
+                 
    
+                     Up to three orthogonal, 
+                         transparent
+                         slices
+                      (useful when superimposed on another volume!):
+                 
    
+                 
    
+                     
+                 
    
+                 
    
+                     If the Volume has been detected as
+                     the results of some computations, transparency is inversely
+                     proportional to the intensity. Otherwise, transparency is constant.
+                 
    
+             
  • 
+                 
    
+                     Up to three orthogonal, opaque slices:
+                 
    
+                 
    
+                     
+                 
    
+                 
    
+                     You can select which planes you want to see
+                     or hide, and move them with the mouse.
+                     Brightness and contrast
+                     can be adjusted.
+                 
    
+             
  • 
+                 
    
+                     Transparent isosurface:
+                 
    
+                 
    
+                     
+                 
    
+                 
    
+                     The surface is transparently drawn, so you can 
+                         link
+                         other windows into it
+                     , and see through its surface.
+                 
    
+             
  • 
+                 
    
+                     Opaque isosurface:
+                 
    
+                 
    
+                     
+                 
    
+                 
    
+                     The surface is drawn opaque, which will hide any other contained 
+                         linked
+                         windows
+                     . In this case use the previous renderings (or the
+                     infamous "Depth-shift trick" for
+                     the inner window).
+                 
    
+         

+         

+             Change the Isosurface cutting value  
+         

+         

+             Dynamically adjust the isosurface
+             cutting value (or background threshold value).
+             By holding the mouse's right button
+             down, moving upward increases the isosurface cutting value
+             (therefor "shrinking" the volume appearance), and the
+             opposite when moving downward.
+         

+         

+             During this process, only a low resolution version of the
+             volume is displayed, to gain speed. Only when releasing the button
+             the full resolution isosurface will be computed, and displayed. You
+             can have a short time lag before the final isosurface appears, due to
+             this computationally expensive process. Also, some geometrical
+             details hidden in the low resolution display will appear in the
+             higher resolution. You will get use to it, and you can re-adjust very
+             quickly by again using the mouse, or with the 
+                 options
+                 menu
+             .
+         

+         

+             For those interested in technical details, up to 6 volumes are cached
+             by the isosurface functions. The first access to the isosurface will
+             copy the volume, then filters it, and later calls will only use this
+             cache, again, for an overall gain in speed.
+         

+         

+             Colorize the exterior surface  
+         

+         

+             Usually, the exterior surface of a volume appears with a predefined
+             exterior color (kind of shiny, silver-like). When activating this
+             button, you can assign a color of your choice to the exterior surface.
+             This can be helpful to discriminate between different volumes (or
+             just because you like colors).
+         

+         

+             The colors at your disposal are the ones in the current 
+                 Color
+                 Table
+             , so you may have to change it to have the right colors.
+             The exterior surface actually "has a value" set to the
+             current Isosurface cutting value, so its
+             color is the one picked in the color table with this value. This
+             means that changing the Isosurface cutting value will also change the
+             color (no headache, this is intuitive). Also, changing  the 
+                 Brightness
+                 level
+              (or the Contrast level) will also
+             affect the color chosen, and this is rather the way to go.
+         

+         

+              
+         

+         

+             Here is an example, with the same Isosurface cut, first without the
+             colorization, then with colorization and with two different brighness levels:
+         

+         

+             
+         

+         

+             And another example with the same brightness level, but with
+             increased Isosurface cutting values:
+         

+         

+             
+         

+         

+             And finally, if a volume has been 
+                 detected
+                 as a ROI volume
+             , many exterior colors are used, one for each
+             underlying ROI values:
+         

+         

+             
+         

+         

+             Editing / cutting into the volume  
+         

+         

+             You have here a set of tools (currently 5) to help you edit / cut / remove
+             some unwanted parts of the current volume:
+         

+         
    
+             
  • Deleting a centered sphere
    • 
+             
  • Blurring within a centered sphere
    • 
+             
  • Deleting a cylinder perpendicular to surface
    • 
+             
  • Deleting a sphere perpendicular to surface
    • 
+             
  • Deleting below a plane perpendicular to surface
    • 
+         

+         

+              
+         

+         

+             You 
+                 switch between these tools by repeatedly pressing on the cutting
+                 button
+             . And you quit the editing mode after the last tool, or after
+             pressing the Esc key.
+         

+         

+             Every tool will graphically display itself as some sort of 
+                 reddish,
+                 semi-transparent object
+             . The tool will adapt itself in 
+                 real
+                 time
+              to the current position your pointing at.
+         

+         

+             There will also be some hint showing up at the bottom of the display,
+             to remind you in which editing mode you currently are.
+         

+         

+             Finally, simply Middle-clicking with the mouse will 
+                 apply the
+                 tool
+              at your current position, deleting all data inside.
+         

+         

+             Deleting Centered Sphere
+         

+         

+             A reddish sphere appears:
+         

+         
    
+             
  • centered under the current mouse position
    • 
+             
  • 
+                 its radius can be adjusted with a 
+                     right-click
+                     + moving left-right
+                 
+             
    • 
+         

+         

+              
+         

+         

+             Useful to delete big floating blobs, or clipping some round regions in the
+             volume: 
+         

+         

+             
+         

+         

+             Blurring Centered Sphere
+         

+         

+             3 concentric reddish spheres appear:
+         

+         
    
+             
  • centered under the current mouse position
    • 
+             
  • 
+                 their radiuses can be adjusted with a 
+                     right-click
+                     + moving left-right
+                 
+             
    • 
+             
  • 
+                 The inner sphere shows where the maximum blurring
+                 will occur.
    No blurring will be applied past the outer sphere.
    
+                 The in-between sphere shows the half-blurring limit.
+             
    • 
+         

+         

+              
+         

+         

+             Very useful to anonymize a full head, so that the individual's face could not
+             be recognizable anymore. You might have to apply the filter a few times to
+             achieve the desired level of blurriness, while changing location a bit while
+             doing so. And of course, work on a copy of the original head!
+         

+         

+             Note that the internal parts of the MRI get also blurred,
+             and not only the face, which might also affect the brain itself. So don't
+             attempt to extract the brain on the blurred head, the latter is 
+                 merely for display and not other processing
+             !
+         

+         

+             
+         

+         

+             Deleting Cylinder perpendicular to surface
+         

+         

+             A reddish cylinder appears:
+         

+         
    
+             
  • centered under the current mouse position
    • 
+             
  • 
+                 its radius can be adjusted with a 
+                     right-click
+                     + moving left-right
+                 
+             
    • 
+             
  • 
+                 its length can be adjusted with a 
+                     right-click
+                     + moving up-down
+                 
+             
    • 
+             
  • 
+                 its direction is the local gradient
+                 ("perpendicular" to data)
+             
    • 
+         

+         

+              
+         

+         

+             This is useful to punch all sorts of holes that are not spherically shaped:
+         

+         

+             
+         

+         

+             Deleting Sphere perpendicular to surface
+         

+         

+             A reddish sphere appears:
+         

+         
    
+             
  • 
+                 it is tangent to the current surface it touches,
+                 always pointing outwardly
+             
    • 
+             
  • 
+                 its radius can be adjusted with a 
+                     right-click
+                     + moving left-right
+                 
+             
    • 
+             
  • 
+                 it uses the local gradient ("perpendicular" to data)
+                 to point "outside"
+             
    • 
+         

+         

+              
+         

+         

+             This sphere differs from the first one by how it lands on the data. First one
+             is centered on the position you point. While this one simply touches the
+             surface of the volume. This is useful to delete stuff floating outside
+             of an object of interest (which will remain intact):
+         

+         

+             
+         

+         

+             Deleting below plane perpendicular to surface
+         

+         

+             A reddish plane appears, shown as a big disk:
+         

+         
    
+             
  • centered under the current mouse position
    • 
+             
  • 
+                 its normal is the local gradient ("perpendicular" to
+                 data)
+             
    • 
+             
  • 
+                 it might be necessary to zoom out the object to have a better view of
+                 the cutting plane whereabout
+             
    • 
+         

+         

+              
+         

+         

+             This will cut all data on the one side of the plane shown by the gradient
+             vector:
+         

+         

+             
+         

+         

+             Other hints
+         

+         
    
+             
  • 
+                 
    
+                     The cutting tools are all fully in 3D, you might need to rotate your
+                     object at hand to get the right view and the right shot!
+                 
    
+             
  • 
+                 
    
+                     If you use some clipping plane, then you can
+                     totally cut inside the volume...
+                 
    
+             
  • 
+                 
    
+                     Before you begin, make and use a copy of the volume you want to edit, so as to
+                     not alter the original file!
+                 
    
+             
  • 
+                 
    
+                     Save file often, every time when you are fine with the current results.
+                     Then you can use the  File | Revert 
+                     to undo the last operation!
+                 
    
+             
  • 
+                 
    
+                     All operations incorporate some kind of anti-aliasing, so
+                     that the resulting cuts look natural.
    However this 
+                         does not
+                         apply to masks
+                     , which are rather cut "sharply". This is to prevent
+                     creating new intermediate values, a definitive no-no for
+                     masks or ROIs.
+                 
    
+         

+         

+             Clipping plane Coronal  
+         

+         

+             Select a Coronal clipping ("cutting") plane (see below).
+         

+         

+             Clipping plane Transverse  
+         

+         

+             Select a Transverse clipping ("cutting") plane (see below).
+         

+         

+             Clipping plane Sagittal  
+         

+         

+             Select a Sagittal clipping ("cutting") plane.
+         

+         

+              
+         

+         

+             If in the slice rendering modes,
+             it simply toggles the planes on or off:
+         

+         

+             
+         

+         

+             If in the volume rendering modes, it
+             cuts the volume, showing one half first, then the second half,
+             and then off again:
+         

+         

+             
+         

+         

+             In the case above the clippping planes can also be cumulated,
+             then only the intersection of the 2 or 3 planes are clipped (note
+             that it will become more computationally demanding):
+         

+         

+             
+         

+         

+             All in all, you have 8 clipping combinations, 2 in each axis,
+             allowing to clip any octant.
+         

+         

+             See also the related topic of 
+                 searching
+                 and displaying the orientation
+             .
+         

+         

+             Slice mode  
+         

+         

+             You switch to a serie of 2D slices:
+         

+         

+             

+             By pressing many times on the button, you have access to coronal,
+             transverse and sagittal displays.
+         

+         

+             The previous 3D display is still used (and might be modified
+             as well), following the last slice, as to give an idea of  where
+             the slices are actually cutting.
+         

+         

+             You can still rotate
+             the slices, if the orientation does not fit your taste.
+         

+         

+             More or less slices  
+         

+         

+             While keeping the first and last slices position fixed, this will
+             either add or remove intermediate slices. If pressing the Shift
+             key at the same time, it either add all the slices between the
+             current extremes, or remove all slices at once.
+         

+         

+             Move first slice  
+         

+         

+             Move the first slice forward or backward, the meaning of it being
+             dependent of what is the current slice mode (coronal, transverse or
+             sagittal). If pressing the Shift key at the same time, it will
+             step faster each time.
+         

+         

+             Move last slice  
+         

+         

+             Move the last slice forward or backward, the meaning of it being
+             dependent of what is the current slice mode (coronal, transverse or
+             sagittal). If pressing the Shift key at the same time, it will
+             step faster each time.
+         

+         

+             Show Max  
+         

+         

+             Draws a symbol at the maximum position, which can be either:
+         

+         
    
+             
  • 
+                 
    
+                     A transparent circle, always on top of the display /
+                     volume, even if the max itself is not directly in sight:
+                 
    
+                 
    
+                     
+                 
    
+             
  • 
+                 
    
+                     A solid 3D cross, visible only if the perspective
+                     allows it:
+                 
    
+                 
    
+                     
+                 
    
+         

+         

+             The slices are not automatically positionned at the max. If
+             you want to do that use the 
+                 Find Max
+                 position button
+              (below).
+         

+         

+             Find Max position  
+         

+         

+             This will position the current cutting plane(s) at the maximum position.
+         

+         

+             It will not automatically show where the max is on the
+             cutting plane, though. To that aim, use the 
+                 Show
+                 Max button
+              (above).
+         

+         

+              
+         

+         

+             Here the max is shown as a 3D cross, and
+             the Find Max position is not activated (top pictures), then
+             activated (bottom pictures):
+         

+         

+             
+         

+         

+             
+         

+         

+              
+         

+         

+             Brightness  
+         

+         

+             Only when you have some clipping planes
+             active, it changes the brightness of the slices displayed. It also
+             works in the special case of 
+                 isosurface
+                 coloring
+             .
+         

+         

+             Technically, there is a mapping from values to colors, and increasing
+             the brightness decreases the maximum value (indicated above the color
+             scale) mapped to the maximum color, therefor making lower values
+             appear brighter:
+         

+         

+             
+         

+         

+             Contrast  
+         

+         

+             Contrast does not change the maximum value mapped to the maximum
+             color, but changes the slope of the mapping, increasing or
+             decreasing the color differences between low and high values.
+         

+         

+             Low contrast is achieved through a linear mapping of the values to
+             the colors. Higher contrasts are done by an exponential mapping (as a
+             Gamma correction), making low values appear dimmer, and high values
+             appear brighter:
+         

+         

+             
+         

+         

+             Note in the pictures above, that the maximum mapped value has not
+             changed. Though the appearance of the color scale (on the right) has
+             changed, correctly reflecting the non-linear color mapping (more
+             colors for higher values when increasing contrast).
+         

+         

+             Color auto scaling  
+         

+         

+             Sets the maximum volume value to the maximum color value. Put it
+             another way: automatically sets the brightness to match and correctly
+             display the data. Consequently, the brightness
+             buttons become inactive, but still the contrast
+             can be adjusted.
+         

+         

+             Color modes  
+         

+         

+             Cycles through different color tables (black to white, white to
+             black, black to yellow to white, etc...):
+         

+         

+             
+         

+         

+             MRI - Mouse
+         

+         

+             Go here for the mouse actions
+             common to all views.
+         

+         

+             Changing the Isosurface cutting value
+         

+         

+             While in Isosurface mode, by holding the
+             mouse's right button down, moving upward will increase
+             the isosurface cutting value, therefore "shrinking" the
+             volume. Conversely, moving downward will increase the
+             isosurface cutting value, "inflating" the volume.
+         

+         

+              
+         

+         

+             The visual hints
+             associated with the isosurface:
+         

+         

+             

+                 
+             

+         

+         

+             MRI - Keyboard
+         

+         

+             See the general 3D keyboard
+             and basic window keyboard actions.
+         

+         

+             MRI - Menus
+         

+         

+             Filters menu
+         

+         

+             A whole bunch of filters are here for you to play with, enjoy!
+         

+         

+             The filters apply to the current MRI at its current state. Here are
+             the main families of filters:
+         

+         

+              
+         

+         
    
+             
    
+                 Denoising
+             
    
+             
      
+                 
      
+                     All you need for cleaning up MRIs: Gaussian, Median, Mean...
+                 
      
+             
    
+             
    
+                 Arithmetic
+             
    
+             
      
+                 
      
+                     Arithmetic operation like intensity rescaling.
+                 
      
+             
    
+             
    
+                 Histogram
+             
    
+             
      
+                 
      
+                     Comuting histograms, Equalization, Compacting equalized histograms.
+                 
      
+             
    
+             
    
+                 Mask
+             
    
+             
      
+                 
      
+                     Thresholding, binarization, combining & applying masks, plus a
+                     bunch of operations on the neighborhood density.
+                 
      
+             
    
+             
    
+                 Morphology
+             
    
+             
      
+                 
      
+                     Classical Dilate / Erode / Open / Close, plus some more like
+                     Thinning, Waterfall...
+                 
      
+             
    
+             
    
+                 Partial Derivatives
+             
    
+             
      
+                 
      
+                     Gradient, Laplacian, Hessian, k Curvature...
+                 
      
+             
    
+             
    
+                 Statistics
+             
    
+             
      
+                 
      
+                     Mean, SD, Coefficient of variation, Median, Mode, MAD, IQR, Entropy etc...
+                 
      
+             
    
+             
    
+                 Brain processing
+             
    
+             
      
+                 
      
+                     Bias Field Correction
+                 
      
+                 
      
+                     Grey Matter segmentation
+                 
      
+                 
      
+                     White & Grey matter segmentation
+                 
      
+                 
      
+                     Skull stripping
+                 
      
+             
    
+         

+         

+             Options menu
+         

+         
    
+             
    
+                 Specify another Isosurface thresold value
+                 
    
+         
    
+             
+                 Specify another Isosurface
+                 downsampling quality
+             
+             
      
+                 Big MRI's or volumes (dimensions > 128) have a downsampled
+                 isosurface by default. It does not affect the data displayed on
+                 slices,
+                 but just the outer look of the surface. Downsampling makes the
+                 surface lighter and faster in memory, at the expense of a loss of
+                 spatial precision. If you want maximum precision (for that nice
+                 snapshot...), change this downsampling to 1 (can eat up to 50 M of
+                 memory!), and on the contrary, if you don't bother, you might
+                 increase it (though not so useful above 2).
+         
      
+         
      
+              
+         
      
+         
    
+         
    
+             Set orientation flags
+             
      
+                 Force Cartool to assign an orientation meaning to the X,Y and Z axis,
+                 like X pointing to the Right, Y pointing Anterior, and Z pointing up.
+         
      
+         
    
+         
    
+             Reset orientation flags
+             
      
+                 Cancel the orientation specified by the user.
+         
      
+         
    
+         
    
+             Set new Origin
+             
      
+                 Set the voxel of origin, i.e. the one that will become coordinates (0,0,0).
+         
      
+         
      
+              
+         
      
+         
    
+         
    
+             Show/hide informations
+             
      
+                 Show or hides some summary about the data.
+         
      
+         
    
+         
    
+             Show/hide color scaling
+             
      
+                 Does what it says (the color scaling is the thing on the right).
+         
      
+         
    
+         
    
+             Show/hide axis
+             
      
+                 Show or hides the X, Y, Z axis.
+         
      
+         
    
+         
    
+             Show/hide orientation
+             
      
+                 Toggles on or off the orientation cues (top, bottom, left, right,
+                 front, back) displayed on the sides of the window.
+         
      
+         
    
+         
    
+              
+         
    
+         
    
+             Flip along X axis
+             
      
+                 Permute the data along the X axis.
+         
      
+         
    
+         
    
+             Flip along Y axis
+             
      
+                 Permute the data along the Y axis.
+         
      
+         
    
+         
    
+             Flip along Z axis
+             
      
+                 Permute the data along the Z axis.
+         
      
+         
    
+         
    
+             Flip X and Y axis
+             
      
+                 Permute the data along the X and Y axis.
+         
      
+         
    
+         
    
+             Flip Y and Z axis
+             
      
+                 Permute the data along the Y and Z axis.
+         
      
+         
    
+         
    
+             Flip X and Z axis
+             
      
+                 Permute the data along the X and Z axis.
+         
      
+         
    
+         
    
+              
+         
    
+         
    
+             'Depth shifting' trick (see here
+             for full explanations)
+             
      
+                 Off
+                 
        
+                     turn it off, back to normal behavior.
+         
        
+         
      
+         
      
+             Light
+             
        
+                 allow a depth shift up to 12% of the maximum depth.
+         
        
+         
      
+         
      
+             Medium
+             
        
+                 allow a depth shift up to 25% of the maximum depth.
+         
        
+         
      
+         
      
+             High
+             
        
+                 allow a depth shift up to 37% of the maximum depth.
+         
        
+         
      
+         
      
+             Maximum
+             
        
+                 allow a depth shift up to 50% of the maximum depth (half of the volume).
+         
        
+         
      
+         
    
+         

+         

+             MRI - Technical points
+         

+         

+             Initial background threshold value
+         

+         

+             When opening (or modifying) a volume, it is needed to estimate the
+             value below which is only noise (or null data), and above which are
+             significant data. This value is called the background threshold value,
+             and is also used as the inital 
+                 isosurface
+                 cutting value
+             .
+         

+         

+             Though it seems very intuitive to you when a looking at the data,
+             remember you are using a very complex image analysis processing
+             called the human visual system. But when it comes to an automatic
+             process, things get tougher, so here is the method currently in use:
+         

+         

+             Cartool first computes a downsampled histogram of the volume, then
+             cuts at the first valley following the first peak. The first peak
+             usually designates the background voxels values, which are more or
+             less the most numerous low values voxels. So cutting just after the
+             peak end usually leads to the best results.
+         

+         

+             Remarks:
+         

+         
    
+             
  • 
+                 
    
+                     The algorithm also cares for the special case where a volume has been
+                     partially extracted and embeded into another one. This could give 2
+                     low values peaks, one for value 0 (null/empty background), and
+                     another one with the original, noisy background.
    
+             
  • 
+                 It also behaves nicely (usually) even when values
+                 have been redistributed over the full range of possible values,
+                 modifying the dynamic range of the data, and giving a comb-like histogram.
    
+             
  • 
+                 Finally, Cartool will restrain the background
+                 threshold value not to exceed 25% of the whole dynamic range of the
+                 data (it is supposed to be a background value).
    
+         

+         

+             Background threshold value can be modified later on, either through
+             this option, or by the 
+                 interactive
+                 isosurface
+              process.
+         

+         

+             Background threshold value is implicitly used when searching for the orientation,
+             and can therefor affect its proper detection.
+         

+         

+             Guessing what the volume actually is
+         

+         

+             Though not a vital point, Cartool tries to guess what the heck is
+             that volume you just opened! It has absolutely 
+                 no influence on the
+                 content itself
+             , and it will not modify anything in it!
+             However, Cartool uses its guess to tune up a few parameters for a
+             better display, like the isosurface smoothness, the isosurface
+             cutting value, the colors, etc...
+         

+         

+              
+         

+         

+             Cartool will "guess" between these different types of volumes:
+         

+         
    
+             
  • 
+                 
    
+                     A Full Head, that means, an original scan that has not been
+                     (that much) modified. The surface is made "smooth", with
+                     default black-to-white colors:
+                 
    
+         

+         

+             

+                 
+             

+         

+         
    
+             
  • 
+                 
    
+                     A Segmented Brain, that is an original scan that has been
+                     clipped to some of its parts (grey matter, white matter, etc...). The
+                     surface is made "smooth", with black-to-white colors:
+                 
    
+         

+         

+             

+                 
+             

+         

+         
    
+             
  • 
+                 
    
+                     A Binary Mask, which contains only 2 values (0 and whatever).
+                     The surface is made to look "LEGO-like" as to reflect the
+                     idea of a mask, and with black-to-white colors:
+                 
    
+         

+         

+             

+                 
+             

+         

+         
    
+             
  • 
+                 
    
+                     A ROI Mask, which is made of regions with arbitrary fixed
+                     values. The surface is made to look "LEGO-like" as to
+                     reflect the idea of a mask, with an 
+                         external
+                         coloring
+                      done from the ROI's values, and with rainbow-ish colors:
+                 
    
+         

+         

+             

+                 
+             

+         

+         
+         

+             
+         

+         
    
+             
  • 
+                 
    
+                     A Blob, usually the results of some computations. The surface
+                     is made "not-too-smooth", with rainbow-ish colors:
+                 
    
+         

+         

+             

+                 
+             

+         

+         
    
+             
  • 
+                 
    
+                     None of these.
+                 
    
+         

+         

+             Searching for the orientation
+         

+         

+             Cartool tries to "understand" by itself the orientation of
+             the data inside the volume. There are many reasons to do this.
+             Firstly, there are many formats supported in Cartool, and not all of
+             them do include informations on how oriented the data are. Secondly,
+             though some formats have the ability to describe the orientation, it
+             may not be used, or even worse, may be used erroneously. And finally,
+             there are people who like to define an orientation system of their
+             own, and you have to guess which one in the 48 possible systems.
+         

+         

+             So the best solution is simply to ignore all this mess. Cartool will
+             read a volume as it is written in the file and will not attempt
+             anything to re-orient it (i.e. coregistration is the user's responsability).
+             However, it will try to guess, as we are dealing with (some sort of)
+             brains and heads, how it is oriented to simplify and ease the
+                 manipulation and display
+             :
+         

+         

+             
+         

+         
    
+             
  • 
+                 
    
+                     Flags are displayed on the borders of the window, showing the closest
+                     possible indications for the projected axis.
+                 
    
+             
  • 
+                 
    
+                     Rotating the object will automatically update the flags' positions
+                     and contents (just try it!).
+                 
    
+             
  • 
+                 
    
+                     Using the default orientation button,
+                     you can cycle through 6 predefined rotations, consistent for all
+                     volumes (sagittal, coronal and transverse views, on both side).
+                 
    
+             
  • 
+                 
    
+                     You can still turn off the display through 
+                         this
+                         option
+                     .
+                 
    
+         

+         

+              
+         

+         

+             I will not describe the algorithm used here, as it has not been
+             published, and is still under development. Enough to say it works by
+             scanning the volume, sequentially finding axis by looking for
+             symetries, center of gravity, and a few other appropriate methods. It
+             has been tested on a lot of volumes, of low and high resolutions,
+             extracted brains or full heads, partially cut or complete, MRIs or
+             PETs, etc... But still the result may be incorrect if there are
+             unwanted artifacts in the volume. In any case, it will not modify nor
+             interfere with the real data.
+         

+         

+             The success of the detection will depend on the initial 
+                 background
+                 threshold value
+             , so an incorrect threshold is very likely to
+             give an incorrect orientation. Cartool also waits for something 
+                 like
+                 a brain
+             , so if the volume is not looking close to this (say,
+             your grandfather's watch), the result is simply unpredictable (though
+             sometimes it works!). If the detection totally fails, the flags are
+             simply "X Max", "X Min", "Y Max" etc...
+         

+         

+             'Depth shifting' trick
+         

+         

+             In the real world, an object and its image are (without entering in a
+             metaphysical discussion) at the same place. So you can touch what you
+             see, except for holograms, right?

+             Now with computers, you can do more un-natural tricky things. In the
+             present case, we can introduce a shift between the depth position
+             of the "object" (where it is), and its image (where
+             we see it). So it will appear rather normally, though its position is
+             actually displaced toward the viewer (you / the screen).
+             Intuitively, we will see the object contained into another one,
+             displayed "on top" of it instead of being occluded. See an
+             example with 3 increasing depth shifts:
+         

+         

+             
+         

+         

+             Though the full head is opaque, and the brain is inside (well,
+             usually...), with increasing the depth shift we can visualize up to
+             the half of the brain (the maximum) seen on top of the head. But 
+                 this
+                 is not by any mean a "projection onto the surface" of the head
+             .
+         

+         

+             The depth shift is limited to up to the half of the object, therefor
+             hiding its furthest half in all cases (in the example above, we will
+             never see the left hemisphere of the brain, as we see from the right side).
+         

+         

+              
+         

+         

+             Very important notice:
+         

+         

+             Once a shift has been introduced, 
+                 you could easily induce a
+                 misinterpretation of where the data really are
+              while rotating the
+             volume. I therefor strongly recommend to use it very cautiously,
+             and to favor orthogonal simultaneous views only.

+             See an example of possible misinterpretation due to small rotations,
+             the inner blob is nearly central but can be made as if it were on the
+             left or on the right side:
+         

+         

+             
+         

+         

+             Talairach coordinates in MRI
+         

+         

+             Talairach coordinates are, at the moment, hardwired into the code and
+             therefor available only for a restricted set of MRI files: the
+             MNI / McGill standard brains.
+         

+         

+             The files which Cartool recognizes can only be the following:
+         
    *MNI152T1*.hdr
    MNI152.Nlin*.hdr
            
    avg152T1_smac_brain.hdr
    avg152T1_smac_grey.hdr
    avg152T1_smac_pro.hdr
    avg152T1_smac_pro_grid.3005p.spi
            
    ave152_sym_brain.hdr
    ave152_sym_grey.hdr
    ave152_sym_pro.hdr
    ave152_sym_pro_grid.2738p.spi
            
    avg152T1.fld

+              
+         

+         

+             Only then are these functionalities available:
+         

+         

+              
+         

+         
    
+             
  • 
+                 
    
+                     
+                         Tools | Geometry transform
+                         (set of points)
+                      , from the general menu:
+                 
    
+                 
    
+                     Give one (or more) text file(s), which 
+                         each line contains a set of
+                         3D coordinates
+                      in the original MRI space. Each of these 3D
+                     coordinates will be transformed to Talairach, and outputed in a new
+                     file. F.ex.:
+                 
    
+                 
    
+                      
    
+                     59.877 64.004 31.437   will become   
+                     -6.4474739e+01 -1.2306906e+01  1.7800585e+01
+                 
    
+                 
    
+                      
+                 
    
+                 
    
+                     Note that you can run the Talairach Daemon on this new output file,
+                     to get the corresponding brain areas.
+                 
    
+                 
    
+                      
+                 
    
+             
  • 
+                 
    
+                     You can poll with the mouse
+                     in the volume, and get the Talairach coordinates of the clicked
+                     location, in real-time:
+                 
    
+                 
    
+                     
+                 
    
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+     

  
 
\ No newline at end of file
diff --git a/docs/ReferenceGuide/mris-preprocessing.html b/docs/ReferenceGuide/mris-preprocessing.html
index 073c4c1b..c8109eee 100644
--- a/docs/ReferenceGuide/mris-preprocessing.html
+++ b/docs/ReferenceGuide/mris-preprocessing.html
@@ -16,769 +16,1033 @@
 
  
 
- 
-  

-   MRIs Preprocessing Toolbox

-  

-   

-  

-   This toolbox basically aims to rescale, reorient and 
-   convert 
-   raw MRIs, plus optionally extracting the brain (skull 
-   stripping). These are mandatory steps before 
-   creating Inverse Matrices 
-   for specific subjects. Also, the resulting MRIs are more consistent and have nicer
-   display.

-  

-    

-  

-   Computing RIS Dialog

-   Technical points & hints

-  

-   Anisotropic vs isotropic MRI

-  

-   Downsampling MRI

-  

-   Axis orientations

-  

-   Searching the sagittal plane

-  

-   Searching the MNI transverse plane

-  

-   MNI and geometrical centers

-  

-   Skull stripping

-  

-   Bias Field Correction

-  

-   Results

-  

-   MRIs Preprocessing Dialog

-  

-   Called from the  Tools
-    | MRIs and Volumes | MRIs Preprocessing  menu, the following dialog 
-   appears:

-  

-    

-  

-   MRIs Preprocessing Dialog

-  

-    

-  

-    

-   
-       
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-       
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-       
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-       
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-   

-      

-       Presets

-      

-       You can quickly set the most important parameters according to some 
-	   predefined scenarios. Then check and adjust the parameters to your 
-	   liking.

-      

-       (1) Resolution

-      

-        

-      

-       Voxel Size:  Make Voxels Isotropic

-      

-       Make the X, Y and Z voxel size equal, or isotropic, or 
-	   cubic, or the same, or.. you get the idea.

-       Anisotropic voxels are hard to process with filters, so this step is 
-	   mandatory.

-      

-       Resampling:

-      

-       Change the voxels' resolution, usually through downsampling. The aim is 
-	   to have either better units, or comparable files, or smaller files.

-       There are currently 2 ways to change resolution:

-      

-       New Voxel Size:

-      

-       When selected, give the new (isotropic) voxel size in the next edit 
-	   field.

-       Default is set to 1 [mm].

-       Cartool is able to upsample the input MRI, though it will not visually 
-	   improve it.

-      

-       Downsampling Ratio:

-      

-       The other option is to just apply a downsampling factor.

-       The scaling factor needs not be an integer value, so f.ex. you can 
-	   rescale by 2.56 if it suits you. It could also possibly be less than one, 
-	   which would then leads to upsampling the input file. F.ex. a scaling 
-	   factor of 0.5 would mean doubling the original resolution.

-      

-       (2) Orientation

-      

-        

-      

-       Axis Reorientation:

-      

-       Change "how the axis are organized", for the sake of consistency.

-      

-       MNI Style

-      

-       Data is reordered so as to have:
    
-		  
  • the X axis pointing left to right,
    • 
-		  
  • the Y axis posterior to anterior,
-		  
    • 
-		  
  • the Z axis inferior to superior.
    • 
-	  

-	  

-       Hence refering to the MNI orientation as RAS, Right-Anterior-Superior 
-	   for the three X, Y, Z axis.

-      

-       Axis Pointing Towards:

-      

-       You can specify any other orientation you like, by 
-	   specifying which direction each of the 3 axis are pointing to.

-       Each axis edit field can contain only a single letter among:
    
-		  
  • Left or Right
    • 
-		  
  • Anterior or Posterior
    • 
-		  
  • Inferior or Superior.
    • 
-	  

-	  

-       Note that the resulting orientation should be a 
-	   valid right-hand 
-	   axis system, like f.ex. PIR, ALS or LIP. Cartool will enforce 
-	   this consistency, and will not be enable to proceed if the target 
-	   orientation is invalid.

-      

-       Then Adjusting:

-      

-       After the main axis have been reassigned, some fine-tuning can be 
-	   done.

-      

-       Mid-Sagittal Plane

-      

-       This option will search for the optimal mid-sagittal cutting 
-	   plane, the one plane that anatomically separate the two 
-	   hemispheres.

-       This adjustment is of utmost importance for proper Inverse Solutions, as 
-	   to ensure that an (approximately) equal number of solution points will be 
-	   assigned to each hemisphere.

-       This option is usually set only for subjects' MRIs, but 
-	   is not mandatory for template MRIs.

-      

-       MNI Transverse Plane

-      

-       This option will adjust the transverse cutting plane to 
-	   resemble as much as possible the MNI one.

-       Subjects can be positionned very differently in the MRI scanner, for 
-	   various reason. Thererfor, without realigning the transverse plane, it 
-	   can be difficult to interpret activations when looking at slices alone. 
-	   Aligning the brains to the MNI space makes the brains easier to read, so 
-	   to speak.

-       This step could be compared to a rigid body coregistration to the MNI 
-	   mid-sagittal plane, while still keeping the original size (no 
-	   deformation).

-      

-       (3) Origin

-      

-        

-      

-       Setting New Origin:

-      

-       It is often a good idea to set the origin, or "center",
-	   of the MRI. This will help for any forthcoming 
-	   coregistration f.ex.

-      

-       Only by Default

-      

-       This option will prevent overwriting any existing origin, 
-	   which will therefor be preserved through the transformation process.

-      

-       Always

-      

-       This option, on the other hand, will forcibly set the origin, 
-	   even if a previous origin exists.

-      

-       Where to Set New Origin:

-      

-        

-      

-       MNI Center

-      

-       A very convenient center is to use the MNI origin. The 
-	   resulting origin will be very close, although with some slight variation, 
-	   to the Anterior Commissure chosen in the MNI template.

-       This option is available only when the MNI Transverse plane option has 
-	   also been set (see above).

-      

-       Geometrical Center

-      

-       Another convernient center is to use the geometrical center from 
-	   the brain.

-       This one option gives a more central point than the MNI Center above, the 
-	   latter being more anterior.

-      

-       At this Original Position:

-      

-       Last option is for the user to give some explicit coordinates, 
-	   from the original voxel space (not the target space).

-      

-       (4) Volume Size

-      

-        

-      

-       Transformed Volume Size is:

-      

-       You can have some controls on the final volume size, which can come in 
-	   handy in some cases.

-      

-       Proportional to Original Size

-      

-       The output size will follow the transform you applied on the 
-	   data:
    
-		  
  • downsampling by 2, output size is input size divided by 2
    • 
-		  
  • changing the origin, or the axis orientation, output size is equal 
-		  to input size
    • 
-		  
  • Sagittal and Transverse plane adjustments however will produce new 
-		  sizes that fit the results
    • 
-	  

-		   

-      

-       Optimally Re-Cut

-      

-       The output volume will be cropped to the closest as possible to 
-	   the output content. This option can dramatically (yes, drama) 
-	   reduce the actual size of big volumes with lot of empty spaces.

-       This option is mostly used in conjunction with the Sagittal and 
-	   Transverse planes search. These will rotate the MRI, and trying to 
-	   encompass the edges of the new volume will result in very big, and nearly 
-	   empty, files.

-        

-       Important: this option works on a file-by-file 
-	   basis, each file will be evaluated and cropped differently 
-	   according to their contents! If you  happen to process a full head 
-	   then the corresponding brain, each file will be cropped differently. 
-	   Cartool can still work with these 2 files, but most of other packages 
-	   will not.

-      

-       this Specified Size:

-      

-       You want some specific size? Here is your chance, provide the X, 
-	   Y, Z sizes of the output volumes.

-       If you provide a smaller size than the output content, 
-	   some clipping will occur. Cartool tries to behave 
-	   nicely, though, by centering the data first, then clipping the edges 
-	   only, so you might still be OK with the results.

-       If you provide a bigger size than the output content, 
-	   some empty padding will be added equally on all sides.

-      

-       (5) Options

-      

-        

-      

-       Post-processing Full Head:

-      

-       If the input files are full head MRIs, you can choose some more handy 
-	   post-processing.

-      

-       Skull Stripping

-      

-       Extract the full brain from the head, and save it to another file.

-      

-       Method 1 - Fast

-      

-       Earliest and fastest method. You might use it if the default method 2 
-	   fails.

-      

-       Method 2 - Best

-      

-       Latest method, the recommended one, which is a bit slower than method 1. 
-	   It rarely fails, but if it does, you can then use method 1 as a fallback.

-      

-       Bias Field Correction

-      

-       It is usually a very good idea to also correct for the Bias Field of the 
-	   extracted brain.

-       Note that the Bias Field Correction does not apply to the full 
-	   head MRI.

-      

-       Optional Filename Postfix:

-      

-       You can give a meaningful file name postfix for all the resulting files.

-       If empty, Cartool will generate a postfix based on all the preprocessing 
-	   steps applied.

-      

-       Opening Results

-      

-       What is says. However, this could be reset for big batches of files.

-      

-       Process Current

-      

-       Enabled when called from a MRI window, the 
-       preprocessing will apply only to this file.

-      	 

-      

-       Batch Process

-      

-       Enabled when not called from a 
-	   MRI window:

-      
    
-       
  • 
-       
    
-        Clicking this button will open a dialog from which you can select a set
-         of MRI files, within a single directory.
    
-       
  • 
-       
    
-        Using Drag & Drop, you can drop files in the dialog and 
-        process them directly. Plus, it allows you to pick files from 
-        different directories, if you can select them through a handy 
-        utility like Everything beforehand.
    
-       

-      

-        

-		   

-      

-       Cancel

-      

-       Quit the dialog.

-      

-       Help

-      

-       Launch the Help to the right page (should be here...).

-  

-   MRIs Preprocessing - Technical points & hints

-  

-   Anisotropic vs isotropic MRI

-  

-   This is what an anisotropic MRI looks like, with voxels of 
-   unequal dimensions:

-  

-   

-  

-   This is mainly a side-effect of how the MRI scanner performed the 
-   acquisition. Unfortunately, filters designed for MRIs are usually expecting 
-   isotropic voxels as a way to decrease their implementation's complexity. This 
-   is the main reason why we need to correct for anisotropy.

-  

-   
Here is the isotropic corrected version of the MRI 
-   above, with voxels of equal dimensions:

-  

-   

-  

-    

-  

-   Downsampling MRI

-  

-   This is an example before and after downsampling, showing the loss of 
-   resolution of the downsampled version:

-  

-   

-  

-   
A convenient voxels' resolution is usually 1 [mm], but 
-   donw to 2 [mm] is 
-   totally acceptable for inverse solution matrices, in case you encounter 
-   memory problems or want to speed up things.

-  

-   
Note that Cartool currently allows you to specify any voxel size, or any 
-   downsampling / upsampling values. Just put meaningful values as input 
-   parameters! Avoiding final MRI size bigger than about 256 voxels is kind of 
-   recommanded.

-  

-   Axis orientations

-  

-   According to how the data was scanned, or from which package you took the 
-   data from, you might encounter orientation problems either at the display 
-   level or within your processing pipe-line. This is the main reason why you 
-   might need to reorient your MRIs.


-  

-   Before proceeding, this is a reminder of how Cartool encodes 
-   orientation with a 3 letter string:

-  
    
-	  
  • Orientation is coded with a sequence 3 letters, like 
-	  RAS or PIR
    • 
-	  
  • A letter can only be either L, R, A, P, I or S, each 
-	  standing for:
      
-		  
    • Left vs Right
      • 
-		  
    • Anterior vs Posterior
      • 
-		  
    • Inferior vs Superior.
      • 
-	  
    
-	  
    • 
-	  
  • First letter tells in which direction the X axis is 
-	  pointing to
    • 
-	  
  • Second letter for the Y axis
    • 
-	  
  • Thirs letter for the Z axis
    • 
-  

-	  

-       
So, f.ex., RAS means X axis is pointing toward the Right, Y axis 
-	   pointing toward the Anterior part, and the Z axis pointing toward the 
-	   Superior part

-   

-  

-   Now let's have a look at the same data, shown with 3 different orientations, 
-   respectively PSL, PIR and 
-   ALS (you can tell by looking at the orientation and axis names at 
-   the edge):

-  

-    

-  

-   
In all cases, the targeted orientation has to be geometrically correct, 
-   and be a
-   
-   right-hand axis system:

-  

-    

-  

-   (picture courtesy of
-   Wikipedia, 
-   User:Acdx)

-  

-   

-   

-  

-   In the examples above, the 3 orientations PSL, PIR and 
-   ALS are all indeed right-hand systems:

-  

-        
-        
-   

-  

-   

-  

-   Cartool is checking for you that the orientation you provide is legal. If the dialog is not able to proceed, this could be 
-   because the target 
-   orientation you gave might be wrong. Try to either disable the whole Axis 
-   Reorientation option, or try a legal orientation like RAS, 
-   to see if this was the culprit. If yes, check again your orientation 
-   flags... 

-  

-   Searching the sagittal plane

-  

-   Some MRI data might have the head incorrectly aligned to the sagittal 
-   plane, due to clinical constraints f.ex. Even not visible, this 
-   sagittal plane might still be slightly off. If we want to compute the 
-   Inverse Matrices 
-   for these subjects, there will be a problem with
-   distributing solution 
-   points evenly on each hemispheres.

-  

-   Hence the need to adjust to an optimally cutting sagittal plane.

-  

-   
Here we can see an example of before and after the sagittal plane (shown 
-   as a transparent blue plane) has been adjusted:

-  

-  

-  

-   
Technically speaking, the search for the optimal plane is done by 
-   maximizing the symmetry around a narrow plane, by adjusting 2 angles (roll 
-   and pan) and 1 translation (left-right).

-  

-   Searching the MNI transverse plane

-  

-   For the same reasons as for the sagittal plane, 
-   head placement in the scanner could be such that the transverse slices might 
-   be difficult to interpret. The proposed remedy here is to adjust the 
-   orientation until it looks similar to the MNI transverse plane, which is 
-   itself referring to the Talairach space.

-  

-   Please note that the transverse plane can not be searched unless the
-   sagittal plane 
-   has been done before.

-  

-   
Here we can see an example of before (left) and after (middle) the 
-   transverse plane (shown as a transparent blue plane) has been adjusted, and 
-   the MNI Brain (right) for the sake of comparison:

-  

-  

-  

-   
Technically speaking, the search for the optimal plane is done by 
-   coregistering the sagittal plane to the MNI space, by adjusting 1 angle 
-   (tilt) and 2 translations (up-down and front-back), while ignoring scaling.

-  

-   There is no rescaling done in the final transform, so the Sagittal + 
-   Transverse planes are finally equivalent to a 6-degrees transform (3 
-   translations + 3 rotations). It could be very helpful to have all brains of a 
-   pool of subjects preprocessed this way, as only some scaling (and optionally 
-   some shearing) would be necessary to compute a mean template out of them.

-  

-   MNI and geometrical centers

-  

-   When the MNI transverse plane has been found, we can at the same time recover 
-   the MNI center, which is just above the Anterior 
-   Commissure (AC). Otherwise, it is a good idea to use the 
-   geometrical center of the brain.

-  

-   Here we can see the obtained MNI center (left), compared to the actual MNI 
-   brain (middle), and the geometrical center of the same brain (right):

-  

-   

-  

-   
Again, the MNI center can not be obtained without searching 
-   beforehand for the sagittal plane 
-   and the MNI transverse plane.

-  

-   Skull stripping

-  

-   Skull stripping is the process of extracting the whole brain (grey + white 
-   matter, CSF, cerebellum etc...) out of a full head. Cartool needs this whole 
-   brain to be able to extract 
-   a grey mask during the Inverse Matrices creation.

-  

-   Here you can see the extracted brain (colored) superimposed on top of its 
-   corresponding full head:

-  

-   

-  

-   

-  

-   There are currently 2 skull stripping methods implemented, 
-   the default being the second one, which produces the best results. However, 
-   in case the outcomes of method 2 appear to be really poor, you can try your 
-   chance at method 1. The latter method being usually more robust, at the 
-   expense of a slight loss of resolution.

-  

-   Bias Field Correction

-  

-   MRI scans usually have
-   
-   inhomogeneities in the space domain, called Bias Field. 
-   Without correcting for it, a given brain tissue like the grey matter will 
-   have different values according to their physical position in the scanner. 
-   This is definitely a non-desired property which will hamper the segmentation 
-   of the brain into its constituent tissues.

-  

-   To counter-balance for this inhomogeneity, a process Bias Field 
-   Correction (BFC) is usually applied on the extracted brain.

-  

-   
Here you can see the extracted brain before the BFC (left), where the 
-   central part of the brain appears "brighter". Then the same brain with 
-   BFC (right), giving a uniform range of values for each tissues:

-  

-   

-  

-   
Note that the BFC correction is best applied on an
-   already extracted brain. It could still be 
-   computed and applied on a full head, but with various success. It is however 
-   not mandatory to have the full head BFC, because the algorithm for the 
-   skull-stripping is actually insensitive to the Bias Field (yes, take that).

-  

-   MRIs Preprocessing - Results

-  
    
-   
  • 
-   
    
-    Preprocessed files are written in the same directories as their sources.
-     
    Output file names will either have the user's infix 
-	added, or have a generic infix name composed from all the preprocessing 
-	steps:
    
-   
      
-	   
    • 
-	   
      <input file>.<infix>.hdr
      or
      
-	   
    • 
-	   
        <input file>.<preprocessing string>.hdr
      
-   
    
-   
    Current output file type is always Analyze (.hdr 
-   / .img pairs).
    
-	  
  • 
-      
    
-      Optionally, a file <input file>.Brain.hdr can be output 
-	  if the skull-stripping option has been selected.
    
-   
  • 
-   
    
-    Verbose file .vrb 
-    (text), showing all the parameters.
    
-   

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-    

-    
+ 
+     

+         

+             MRIs Preprocessing Toolbox
+         

+         

+         

+         

+             This toolbox basically aims to rescale, 
+                 reorient and
+                 convert
+                 raw MRIs
+             , plus optionally 
+                 extracting the brain (skull
+                 stripping)
+             . These are mandatory steps before 
+                 creating Inverse Matrices
+             
+             for specific subjects. Also, the resulting MRIs are more consistent and have nicer
+             display.
+         

+         

+              
+         

+         

+             Computing RIS Dialog

+             Technical points & hints
+         

+         

+             Anisotropic vs isotropic MRI
+         

+         

+             Downsampling MRI
+         

+         

+             Axis orientations
+         

+         

+             Searching the sagittal plane
+         

+         

+             Searching the MNI transverse plane
+         

+         

+             MNI and geometrical centers
+         

+         

+             Skull stripping
+         

+         

+             Bias Field Correction
+         

+         

+             Results
+         

+         

+             MRIs Preprocessing Dialog
+         

+         

+             Called from the  
+                 
+                     Tools
+                     | MRIs and Volumes | MRIs Preprocessing
+                 
+               menu, the following dialog
+             appears:
+         

+         

+              
+         

+         

+             MRIs Preprocessing Dialog
+         

+         

+              
+         

+         

+              
+         

+         
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+         

+                     

+                         Presets
+                 

+                     

+                         You can quickly set the most important parameters according to some
+                         predefined scenarios. Then check and adjust the parameters to your
+                         liking.
+                 

+                     

+                         (1) Resolution
+                 

+                     

+                          
+                 

+                     

+                         Voxel Size:  Make Voxels Isotropic
+                 

+                     

+                         Make the X, Y and Z voxel size equal, or isotropic, or
+                         cubic, or the same, or.. you get the idea.
+                     

+                         Anisotropic voxels are hard to process with filters, so this step is
+                         mandatory.
+                 

+                     

+                         Resampling:
+                 

+                     

+                         Change the voxels' resolution, usually through downsampling. The aim is
+                         to have either better units, or comparable files, or smaller files.
+                     

+                         There are currently 2 ways to change resolution:
+                 

+                     

+                         New Voxel Size:
+                 

+                     

+                         When selected, give the new (isotropic) voxel size in the next edit
+                         field.
+                     

+                         Default is set to 1 [mm].
+                     

+                         Cartool is able to upsample the input MRI, though it will not visually
+                         improve it.
+                 

+                     

+                         Downsampling Ratio:
+                 

+                     

+                         The other option is to just apply a downsampling factor.
+                     

+                         The scaling factor needs not be an integer value, so f.ex. you can
+                         rescale by 2.56 if it suits you. It could also possibly be less than one,
+                         which would then leads to upsampling the input file. F.ex. a scaling
+                         factor of 0.5 would mean doubling the original resolution.
+                 

+                     

+                         (2) Orientation
+                 

+                     

+                          
+                 

+                     

+                         Axis Reorientation:
+                 

+                     

+                         Change "how the axis are organized", for the sake of consistency.
+                 

+                     

+                         MNI Style
+                 

+                     

+                         Data is reordered so as to have:
    
+                             
  • the X axis pointing left to right,
    • 
+                             
  • 
+                                 the Y axis posterior to anterior,
+                             
    • 
+                             
  • the Z axis inferior to superior.
    • 
+                         

+                     

+                         Hence refering to the MNI orientation as RAS, Right-Anterior-Superior
+                         for the three X, Y, Z axis.
+                 

+                     

+                         Axis Pointing Towards:
+                 

+                     

+                         You can specify any other orientation you like, by
+                         specifying which direction each of the 3 axis are pointing to.
+                     

+                         Each axis edit field can contain only a single letter among:
    
+                             
  • Left or Right
    • 
+                             
  • Anterior or Posterior
    • 
+                             
  • Inferior or Superior.
    • 
+                         

+                     

+                         Note that the resulting orientation should be a 
+                             
+                                 valid right-hand
+                                 axis system
+                             
+                         , like f.ex. PIR, ALS or LIP. 
+                             Cartool will enforce
+                             this consistency
+                         , and will not be enable to proceed if the target
+                         orientation is invalid.
+                 

+                     

+                         Then Adjusting:
+                 

+                     

+                         After the main axis have been reassigned, 
+                             some fine-tuning can be
+                             done
+                         .
+                 

+                     

+                         Mid-Sagittal Plane
+                 

+                     

+                         This option will search for the 
+                             optimal mid-sagittal cutting
+                             plane
+                         , the one plane that anatomically separate the two
+                         hemispheres.
+                     

+                         This adjustment is of utmost importance for proper Inverse Solutions, as
+                         to ensure that an (approximately) equal number of solution points will be
+                         assigned to each hemisphere.
+                     

+                         This option is usually set only for subjects' MRIs, but
+                         is not mandatory for template MRIs.
+                 

+                     

+                         MNI Transverse Plane
+                 

+                     

+                         This option will adjust the transverse cutting plane to
+                         resemble as much as possible the MNI one.
+                     

+                         Subjects can be positionned very differently in the MRI scanner, for
+                         various reason. Thererfor, without realigning the transverse plane, it
+                         can be difficult to interpret activations when looking at slices alone.
+                         Aligning the brains to the MNI space makes the brains easier to read, so
+                         to speak.
+                     

+                         This step could be compared to a rigid body coregistration to the MNI
+                         mid-sagittal plane, while still keeping the original size (no
+                         deformation).
+                 

+                     

+                         (3) Origin
+                 

+                     

+                          
+                 

+                     

+                         Setting New Origin:
+                 

+                     

+                         It is often a good idea to set the origin, or "center",
+                         of the MRI. This will help for any forthcoming
+                         coregistration f.ex.
+                 

+                     

+                         Only by Default
+                 

+                     

+                         This option will prevent overwriting any existing origin,
+                         which will therefor be preserved through the transformation process.
+                 

+                     

+                         Always
+                 

+                     

+                         This option, on the other hand, will forcibly set the origin,
+                         even if a previous origin exists.
+                 

+                     

+                         Where to Set New Origin:
+                 

+                     

+                          
+                 

+                     

+                         MNI Center
+                 

+                     

+                         A very convenient center is to use the MNI origin. The
+                         resulting origin will be very close, although with some slight variation,
+                         to the Anterior Commissure chosen in the MNI template.
+                     

+                         This option is available only when the MNI Transverse plane option has
+                         also been set (see above).
+                 

+                     

+                         Geometrical Center
+                 

+                     

+                         Another convernient center is to use the 
+                             geometrical center from
+                             the brain
+                         .
+                     

+                         This one option gives a more central point than the MNI Center above, the
+                         latter being more anterior.
+                 

+                     

+                         At this Original Position:
+                 

+                     

+                         Last option is for the user to give some explicit coordinates,
+                         from the original voxel space (not the target space).
+                 

+                     

+                         (4) Volume Size
+                 

+                     

+                          
+                 

+                     

+                         Transformed Volume Size is:
+                 

+                     

+                         You can have some controls on the final volume size, which can come in
+                         handy in some cases.
+                 

+                     

+                         Proportional to Original Size
+                 

+                     

+                         The output size will 
+                             follow the transform you applied on the
+                             data:
+                         
    
+                             
  • downsampling by 2, output size is input size divided by 2
    • 
+                             
  • 
+                                 changing the origin, or the axis orientation, output size is equal
+                                 to input size
+                             
    • 
+                             
  • 
+                                 Sagittal and Transverse plane adjustments however will produce new
+                                 sizes that fit the results
+                             
    • 
+                         

+                 

+                     

+                         Optimally Re-Cut
+                 

+                     

+                         The output volume will be 
+                             cropped to the closest as possible to
+                             the output content
+                         . This option can dramatically (yes, drama)
+                         reduce the actual size of big volumes with lot of empty spaces.
+                     

+                         This option is mostly used in conjunction with the Sagittal and
+                         Transverse planes search. These will rotate the MRI, and trying to
+                         encompass the edges of the new volume will result in very big, and nearly
+                         empty, files.
+                     

+                          
+                     

+                         Important: this option works on a 
+                             file-by-file
+                             basis
+                         , each file will be evaluated and cropped differently
+                         according to their contents! If you  happen to process a full head
+                         then the corresponding brain, each file will be cropped differently.
+                         Cartool can still work with these 2 files, but most of other packages
+                         will not.
+                 

+                     

+                         this Specified Size:
+                 

+                     

+                         You want some specific size? Here is your chance, provide the 
+                             X,
+                             Y, Z sizes of the output volumes
+                         .
+                     

+                         If you provide a smaller size than the output content,
+                         some clipping will occur. Cartool tries to behave
+                         nicely, though, by centering the data first, then clipping the edges
+                         only, so you might still be OK with the results.
+                     

+                         If you provide a bigger size than the output content,
+                         some empty padding will be added equally on all sides.
+                 

+                     

+                         (5) Options
+                 

+                     

+                          
+                 

+                     

+                         Post-processing Full Head:
+                 

+                     

+                         If the input files are full head MRIs, you can choose some more handy
+                         post-processing.
+                 

+                     

+                         Skull Stripping
+                 

+                     

+                         Extract the full brain from the head, and save it to another file.
+                 

+                     

+                         Method 1 - Fast
+                 

+                     

+                         Earliest and fastest method. You might use it if the default method 2
+                         fails.
+                 

+                     

+                         Method 2 - Best
+                 

+                     

+                         Latest method, the recommended one, which is a bit slower than method 1.
+                         It rarely fails, but if it does, you can then use method 1 as a fallback.
+                 

+                     

+                         Bias Field Correction
+                 

+                     

+                         It is usually a very good idea to also correct for the Bias Field of the
+                         extracted brain.
+                     

+                         Note that the Bias Field Correction does not apply to the full
+                         head MRI.
+                 

+                     

+                         Optional Filename Postfix:
+                 

+                     

+                         You can give a meaningful file name postfix for all the resulting files.
+                     

+                         If empty, Cartool will generate a postfix based on all the preprocessing
+                         steps applied.
+                 

+                     

+                         Opening Results
+                 

+                     

+                         What is says. However, this could be reset for big batches of files.
+                 

+                     

+                         Process Current
+                 

+                     

+                         Enabled when called from a MRI window, the
+                         preprocessing will apply only to this file.
+                     

+                 

+                     

+                         Batch Process
+                 

+                     

+                         Enabled when not called from a 
+                             MRI window
+                         :
+                     

+                     
    
+                         
  • 
+                             
    
+                                 Clicking this button will open a dialog from which you can select a 
+                                     set
+                                     of MRI files
+                                 , within a single directory.
+                             
    
+                         
  • 
+                             
    
+                                 Using Drag & Drop, you can drop files in the dialog and
+                                 process them directly. Plus, it allows you to pick files 
+                                     from
+                                     different directories
+                                 , if you can select them through a handy
+                                 utility like Everything beforehand.
+                             
    
+                     

+                     

+                          
+                     

+                 

+                     

+                         Cancel
+                 

+                     

+                         Quit the dialog.
+                 

+                     

+                         Help
+                 

+                     

+                         Launch the Help to the right page (should be here...).
+                 

+         

+             MRIs Preprocessing - Technical points & hints
+         

+         

+             Anisotropic vs isotropic MRI
+         

+         

+             This is what an anisotropic MRI looks like, with voxels of
+             unequal dimensions:
+         

+         

+             
+         

+         

+             This is mainly a side-effect of how the MRI scanner performed the
+             acquisition. Unfortunately, filters designed for MRIs are usually expecting
+             isotropic voxels as a way to decrease their implementation's complexity. This
+             is the main reason why we need to correct for anisotropy.
+         

+         

+             
Here is the isotropic corrected version of the MRI
+             above, with voxels of equal dimensions:
+         

+         

+             
+         

+         

+              
+         

+         

+             Downsampling MRI
+         

+         

+             This is an example before and after downsampling, showing the loss of
+             resolution of the downsampled version:
+         

+         

+             
+         

+         

+             
A convenient voxels' resolution is usually 1 [mm], but
+             donw to 2 [mm] is
+             totally acceptable for inverse solution matrices, in case you encounter
+             memory problems or want to speed up things.
+         

+         

+             
Note that Cartool currently allows you to specify any voxel size, or any
+             downsampling / upsampling values. Just put meaningful values as input
+             parameters! Avoiding final MRI size bigger than about 256 voxels is kind of
+             recommanded.
+         

+         

+             Axis orientations
+         

+         

+             According to how the data was scanned, or from which package you took the
+             data from, you might encounter orientation problems either at the display
+             level or within your processing pipe-line. This is the main reason why you
+             might need to reorient your MRIs.


+         

+         

+             Before proceeding, this is a reminder of 
+                 how Cartool encodes
+                 orientation with a 3 letter string
+             :
+         

+         
    
+             
  • 
+                 Orientation is coded with a sequence 3 letters, like
+                 RAS or PIR
+             
    • 
+             
  • 
+                 A letter can only be either L, R, A, P, I or S, each
+                 standing for:
      
+                     
    • Left vs Right
      • 
+                     
    • Anterior vs Posterior
      • 
+                     
    • Inferior vs Superior.
      • 
+                 
    
+             
    • 
+             
  • 
+                 First letter tells in which direction the X axis is
+                 pointing to
+             
    • 
+             
  • Second letter for the Y axis
    • 
+             
  • Thirs letter for the Z axis
    • 
+         

+         

+             
So, f.ex., RAS means X axis is pointing toward the Right, Y axis
+             pointing toward the Anterior part, and the Z axis pointing toward the
+             Superior part
+         

+             

+         

+         

+             Now let's have a look at the same data, shown with 3 different orientations,
+             respectively PSL, PIR and 
+                 ALS
+              (you can tell by looking at the orientation and axis names at
+             the edge):
+         

+         

+              
+         

+         

+             
In all cases, the targeted orientation has to be geometrically correct,
+             and be a
+             
+                 right-hand axis system
+             :
+         

+         

+              
+         

+         

+             (picture courtesy of
+             
+                 Wikipedia,
+                 User:Acdx
+             )
+         

+         

+             

+         

+         

+             In the examples above, the 3 orientations PSL, PIR and 
+                 ALS
+              are all indeed right-hand systems:
+         

+         

+                  
+                  
+             
+         

+         

+             

+         

+         

+             Cartool is checking for you that the orientation you provide is legal. If the dialog is not able to proceed, this could be
+             because the target
+             orientation you gave might be wrong. Try to either disable the whole 
+                 Axis
+                 Reorientation
+              option, or try a legal orientation like RAS,
+             to see if this was the culprit. If yes, check again your orientation
+             flags... 
+         

+         

+             Searching the sagittal plane
+         

+         

+             Some MRI data might have the 
+                 head incorrectly aligned to the sagittal
+                 plane
+             , due to clinical constraints f.ex. Even not visible, this
+             sagittal plane might still be slightly off. If we want to compute the 
+                 Inverse Matrices
+             
+             for these subjects, there will be a problem with
+             
+                 distributing solution
+                 points evenly on each hemispheres
+             .
+         

+         

+             Hence the need to adjust to an optimally cutting sagittal plane.
+         

+         

+             
Here we can see an example of before and after the sagittal plane (shown
+             as a transparent blue plane) has been adjusted:
+         

+         

+             
+         

+         

+             
Technically speaking, the search for the optimal plane is done by
+             maximizing the symmetry around a narrow plane, by adjusting 2 angles (roll
+             and pan) and 1 translation (left-right).
+         

+         

+             Searching the MNI transverse plane
+         

+         

+             For the same reasons as for the sagittal plane,
+             head placement in the scanner could be such that the transverse slices might
+             be difficult to interpret. The proposed remedy here is to adjust the
+             orientation until it looks similar to the MNI transverse plane, which is
+             itself referring to the Talairach space.
+         

+         

+             Please note that the
+                 transverse plane can not be searched unless the
+             sagittal plan
+                 e
+                 has been done before
+             .
+         

+         

+             
Here we can see an example of before (left) and after (middle) the
+             transverse plane (shown as a transparent blue plane) has been adjusted, and
+             the MNI Brain (right) for the sake of comparison:
+         

+         

+             
+         

+         

+             
Technically speaking, the search for the optimal plane is done by
+             coregistering the sagittal plane to the MNI space, by adjusting 1 angle
+             (tilt) and 2 translations (up-down and front-back), while ignoring scaling.
+         

+         

+             There is no rescaling done in the final transform, so the Sagittal +
+             Transverse planes are finally equivalent to a 6-degrees transform (3
+             translations + 3 rotations). It could be very helpful to have all brains of a
+             pool of subjects preprocessed this way, as only some scaling (and optionally
+             some shearing) would be necessary to compute a mean template out of them.
+         

+         

+             MNI and geometrical centers
+         

+         

+             When the MNI transverse plane has been found, we can at the same time recover
+             the MNI center, which is just above the 
+                 Anterior
+                 Commissure
+              (AC). Otherwise, it is a good idea to use the 
+                 geometrical center of the brain
+             .
+         

+         

+             Here we can see the obtained MNI center (left), compared to the actual MNI
+             brain (middle), and the geometrical center of the same brain (right):
+         

+         

+             
+         

+         

+             
Again, the MNI center can not be obtained without 
+                 searching
+                 beforehand for
+             the sagittal plane
+                 and
+             the MNI transverse plane.
+         

+         

+             Skull stripping
+         

+         

+             Skull stripping is the process of extracting the whole brain (grey + white
+             matter, CSF, cerebellum etc...) out of a full head. Cartool needs this whole
+             brain to be able to 
+                 extract
+                 a grey mask during the Inverse Matrices creation
+             .
+         

+         

+             Here you can see the extracted brain (colored) superimposed on top of its
+             corresponding full head:
+         

+         

+             
+         

+         

+             

+         

+         

+             There are currently 2 skull stripping methods implemented,
+             the default being the second one, which produces the best results. However,
+             in case the outcomes of method 2 appear to be really poor, you can try your
+             chance at method 1. The latter method being usually more robust, at the
+             expense of a slight loss of resolution.
+         

+         

+             Bias Field Correction
+         

+         

+             MRI scans usually have
+             
+                 inhomogeneities in the space domain, called Bias Field
+             .
+             Without correcting for it, a given brain tissue like the grey matter will
+             have different values according to their physical position in the scanner.
+             This is definitely a non-desired property which will hamper the segmentation
+             of the brain into its constituent tissues.
+         

+         

+             To counter-balance for this inhomogeneity, a process 
+                 Bias Field
+                 Correction (BFC)
+              is usually applied on the extracted brain.
+         

+         

+             
Here you can see the extracted brain before the BFC (left), where the
+             central part of the brain appears "brighter". Then the same brain with
+             BFC (right), giving a uniform range of values for each tissues:
+         

+         

+             
+         

+         

+             
Note that the BFC correction is best applied on an
+             already extracted brain. It could still be
+             computed and applied on a full head, but with various success. It is however
+             not mandatory to have the full head BFC, because the algorithm for the
+             skull-stripping is actually insensitive to the Bias Field (yes, take that).
+         

+         

+             MRIs Preprocessing - Results
+         

+         
    
+             
  • 
+                 
    
+                     Preprocessed files are written in the same directories as their sources.
+                     
    Output file names will either have the user's infix
+                     added, or have a generic infix name composed from all the preprocessing
+                     steps:
+                 
    
+                 
      
+                     
    • 
+                         
      <input file>.<infix>.hdr
      or
      
+                     
    • 
+                         
        <input file>.<preprocessing string>.hdr
      
+                 
    
+                 
    
+                     Current output file type is always Analyze (
+                         .hdr
+                         / .img pairs
+                     ).
+                 
    
+             
  • 
+                 
    
+                     Optionally, a file <input file>.Brain.hdr can be output
+                     if the skull-stripping option has been selected.
+                 
    
+             
  • 
+                 
    
+                     Verbose file .vrb
+                     (text), showing all the parameters.
+                 
    
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+              
+         

+              
+     

  
 
\ No newline at end of file
diff --git a/docs/ReferenceGuide/potentials-maps-display.html b/docs/ReferenceGuide/potentials-maps-display.html
index fc210979..6e6b9c3e 100644
--- a/docs/ReferenceGuide/potentials-maps-display.html
+++ b/docs/ReferenceGuide/potentials-maps-display.html
@@ -2,390 +2,560 @@
  
   Scalp and Intracranial Potentials Display
  
- 
-  

-   Scalp & Intracranial Potentials Display

-  

-    

-  

-   If you have no idea how to get this display on the first hand, it 
-   will help if you read this topic first.

-  

-   Buttons

-  

-      

-  

-     

-  

-     

-  

-    

-  

-      

-  

-   

-  

-   Mouse

-  

-   Menus

-  

-   Search

-  
-  

-   Options

-  
-  

-   Technical points

-  

-   How do I get this display?
ROIs and potentials display

-  

-   Potentials - Buttons

-  

-   Rendering  

-  

-   (Go here for basic explanations on rendering)

-   Toggles between 4 display modes:

-  
    
-   
  • 
-   
    
-    No interpolation, small 
-    spheres at each electrode position have a coloring proportional to 
-    the intensity:
    
-   
    
-    
    
-   
  • 
-   
    
-    Using a Delaunay interpolation, triangles between electrodes 
-    have a coloring proportional to the intensity, plus a fixed transparency:
    
-   
    
-    
    
-   
  • 
-   
    
-    Using a Delaunay interpolation, triangles between electrodes 
-    have a coloring proportional to the intensity, plus a transparency 
-    inversely proportional to the intensity (a bit like clouds on top 
-    of the brain...):
    
-   
    
-    
    
-   
  • 
-   
    
-    Using a Delaunay interpolation, triangles between electrodes 
-    have a coloring proportional to the intensity, and are rendered opaque:
    
-   
    
-    
    
-   

-  

-   Show electrodes  

-  

-   Show the electrodes positions. It currently toggles between 3 modes:

-  
    
-   
  • 
-   
    
-    No electrodes,
    
-    
  • Small electrodes,
    
-    
  • Bigger electrodes.
    
-   

-  

-   Show electrode names  

-  

-   Show the names of the electrodes, each name within its own 
-   semi-transparent window.

-  

-   Show tracks on top  

-  

-   This is actually a handy shortcut to the EEG window 
-   itself, to turn it into the 3D tracks rendering,
-    and then applying a graphical link 
-   to see the tracks in 3D superimposed  to the potentials. 
-   See an example here in 3D and in 2D:

-  

-   

-  

-   Plus, you can combine the "tracks on top" 
-   with ROIs.

-  

-   Project in 2D  

-  

-   Enables you to see all your data on a flat surface. Mostly, it does a projection
-    of the 3D model. What has been detected as "the top" 
-   is used as the center of the projection, and everything un-warps from 
-   there (I'm still searching for the name of that projection).

-  

-    It currently toggles between 3 modes:

-  
    
-   
  • 
-   
    
-    Regular, 3D mode,
    
-    
  • Plain 2D,
    
-    
  • 2D plus elevation proportional to intensity and contrast.
    
-   

-  

-   

-  

-   If the electrode model includes more than surface electrodes, that is single
-    electrodes, strips, grids, they will also be rendered in 2D in a synthetic
-    and ordered way. Still the idea is to give the user an idea of 
-   what the data are, avoiding anything to be hidden by another object. 
-   F.ex. a few strips in 3D and then in 2D:

-  

-   

-  

-   Show Min and Max positions  

-  

-   Add a 3D cross where the minimum and maximum values are. It's 
-   also a 3 states buttons, with two different sizes for the 
-   cross availables:

-  

-   

-  

-   Brightness  

-  

-   See the MRI Brightness.

-  

-   Contrast  

-  

-   See the MRI Contrast.

-  

-   Color auto scaling  

-  

-   See the MRI Color auto scaling.

-  

-   Color modes  

-  

-   4 different color modes are possible, for negative / 0 / positive values:

-  
    
-   
  • 
-   
    
-    Blue / White / Red
    
-    
  • Neuroscan-ish colors
    
-    
  • Black / White / Black
    
-    
  • White / Middle grey / Black
    
-   

-  

-   

-   

-  

-   Switch to another electrode coordinates 
-   file  

-  

-   The link file can contain more than one 
-   electrode coordinates file. In this case, you can use any of 
-   these models to show your data. F.ex. you can have a standard (and 
-   smooth) model, plus the actual model (less smooth) of a given 
-   subject, and switch from one to another. F.ex.:

-  

-   

-  

-   Potentials - Mouse

-  

-   See the general mouse actions,
-    and especially the brightness
-    and contrast control and the polling
-    function.

-  

-   Potentials - Menus

-  

-   Search menu

-  
    
-   
    
-    Find TF with maximum value 
    
-   
      
-    
      
-     Scan all Time Frames, and set the 
-     time cursor to the position where the greatest GFP is.
      
-    
    
-   

-  

-   Options menu

-  
    
-   
    
-    Interpolation
    
-   
-   
    
-    Specify a display scaling
    
-   
      
-    
      
-     Ask the user for an arbitrary scaling value, equivalent to setting 
-     the brightness.
      
-    
    
-   
    
-    Show / hide color scaling
    
-   
      
-    
      
-     Does what it says.
      
-    
    
-   
    
-    Show / hide projected axis and equator
    
-   
      
-    
      
-     In 2D mode, this toggles on and off the 
-     display of the projected equator and axis.
      
-    
    
-   
    
-    Show / hide orientation
    
-   
      
-    
      
-     Does what it says.
      
-    
    
-   
    
-    'Depth shifting' trick for 3D potentials
    
-   
      
-    
      
-     If you apply some graphical links, the data are 3D consistents. That 
-     is, anything closer to the viewer will hide what is behind, as we get 
-     used to. In some cases, f.ex. depth electrodes, we wish to see 
-     their display even though they are hidden in the brain. So we can 
-     artificially shift the potentials closer to the viewer, and see them 
-     "on top" of the brain.
      
-    
      
-     Same as the MRI Depth 
-     Shifting topic.
      
-    
      
-     F.ex. depth electrodes wihtout and with depth shifting:
      
-    
      
-     
      
-    
    
-   

-  

-   Potentials - Technical points

-  

-   How do I get this display?

-  

-   This display is actually automatically generated when enough 
-   files have been linked together,
-    and therefore share enough informations together.

-  

-   So, simply put at least these kind of files:

-  
-  

-    

-  

-   Putting many EEG files will display as many maps as there are 
-   of EEGs, but putting many coordinates files does not. This 
-   last case allows you to switch in real-time between different 3D models,
-    f.ex. between a real model from a subject, and an average one. All 
-   the maps of the link being changed at once.

-  

-    

-  

-   Important points:

-  
    
-   
  • 
-   
    
-    Putting many EEG files will display as many maps as there are 
-    of files.
    
-   
  • 
-   
    
-    You can put many coordinates files, but only one is active at a time.
    
-   
  • 
-   
    
-    You have to sure the sequence of the electrodes in the coordinates 
-    file exactly match the sequence of the tracks in the EEG files. 
-    Missing this point leads to totally erroneous results and displays!
    
-   
  • 
-   
    
-    Cartool is doing a lot of checkings to ensure you are on the safe 
-    side of this elaborate display. Though, only you can assert that all 
-    these files match together (the solution points with the MRI space 
-    and the IS matrix).
    
-   

-  

-    

-  

-   Recommended readings: the fabulous Linking
-    Files story, as well as the infamous "windows
-    in slavery".

-  

-   ROIs and potentials display

-  

-   Well, there is no direct control / button for ROIs in the potential 
-   display. This is done through the usual ones, and from the EEG
-    tracks ROI controls.

-  

-   So, if the EEG display is in ROIs mode,
-    showing the tracks on top will show the tracks
-    grouped by roi, with the underlying map unchanged:

-  

-   

-  

-   Now, if the rois are averaged,
-    then the averaged tracks are shown, and the underlying map shows 
-   the averaged values, too (the electrodes not within a roi are set 
-   to zero):

-  

-   

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    
+ 
+     

+         

+             Scalp & Intracranial Potentials Display
+         

+         

+              
+         

+         

+             If you have no idea how to get this display on the first hand, it
+             will help if you read this topic first.
+         

+         

+             Buttons
+         

+         

+                
+         

+         

+               
+         

+         

+               
+         

+         

+              
+         

+         

+                
+         

+         

+             
+         

+         

+             Mouse
+         

+         

+             Menus
+         

+         

+             Search
+         

+         
+         

+             Options
+         

+         
+         

+             Technical points
+         

+         

+             How do I get this display?
ROIs and potentials display
+         

+         

+             Potentials - Buttons
+         

+         

+             Rendering  
+         

+         

+             (Go here for basic explanations on rendering)

+             Toggles between 4 display modes:
+         

+         
    
+             
  • 
+                 
    
+                     No interpolation, small
+                     spheres at each electrode position have a coloring proportional to
+                     the intensity:
+                 
    
+                 
    
+                     
+                 
    
+             
  • 
+                 
    
+                     Using a Delaunay interpolation, triangles between electrodes
+                     have a coloring proportional to the intensity, plus a fixed transparency:
+                 
    
+                 
    
+                     
+                 
    
+             
  • 
+                 
    
+                     Using a Delaunay interpolation, triangles between electrodes
+                     have a coloring proportional to the intensity, plus a 
+                         transparency
+                         inversely proportional to the intensity
+                      (a bit like clouds on top
+                     of the brain...):
+                 
    
+                 
    
+                     
+                 
    
+             
  • 
+                 
    
+                     Using a Delaunay interpolation, triangles between electrodes
+                     have a coloring proportional to the intensity, and are rendered opaque:
+                 
    
+                 
    
+                     
+                 
    
+         

+         

+             Show electrodes  
+         

+         

+             Show the electrodes positions. It currently toggles between 3 modes:
+         

+         
    
+             
  • 
+                 
    
+                     No electrodes,
    
+             
  • Small electrodes,
    
+             
  • Bigger electrodes.
    
+         

+         

+             Show electrode names  
+         

+         

+             Show the names of the electrodes, each name within its own
+             semi-transparent window.
+         

+         

+             Show tracks on top  
+         

+         

+             This is actually a handy shortcut to the EEG window
+             itself, to turn it into the 3D tracks rendering,
+             and then applying a graphical link
+             to see the tracks in 3D superimposed  to the potentials.
+             See an example here in 3D and in 2D:
+         

+         

+             
+         

+         

+             Plus, you can 
+                 combine the "tracks on top"
+                 with ROIs
+             .
+         

+         

+             Project in 2D  
+         

+         

+             Enables you to see all your data on a flat surface. Mostly, it does a 
+                 projection
+                 of the 3D model
+             . What has been detected as "the top"
+             is used as the center of the projection, and everything un-warps from
+             there (I'm still searching for the name of that projection).
+         

+         

+              It currently toggles between 3 modes:
+         

+         
    
+             
  • 
+                 
    
+                     Regular, 3D mode,
    
+             
  • Plain 2D,
    
+             
  • 2D plus elevation proportional to intensity and contrast.
    
+         

+         

+             
+         

+         

+             If the electrode model includes more than surface electrodes, that is 
+                 single
+                 electrodes, strips, grids
+             , they will also be rendered in 2D in a 
+                 synthetic
+                 and ordered way
+             . Still the idea is to give the user an idea of
+             what the data are, avoiding anything to be hidden by another object.
+             F.ex. a few strips in 3D and then in 2D:
+         

+         

+             
+         

+         

+             Show Min and Max positions  
+         

+         

+             Add a 3D cross where the minimum and maximum values are. It's
+             also a 3 states buttons, with two different sizes for the
+             cross availables:
+         

+         

+             
+         

+         

+             Brightness  
+         

+         

+             See the MRI Brightness.
+         

+         

+             Contrast  
+         

+         

+             See the MRI Contrast.
+         

+         

+             Color auto scaling  
+         

+         

+             See the MRI Color auto scaling.
+         

+         

+             Color modes  
+         

+         

+             4 different color modes are possible, for negative / 0 / positive values:
+         

+         
    
+             
  • 
+                 
    
+                     Blue / White / Red
    
+             
  • Neuroscan-ish colors
    
+             
  • Black / White / Black
    
+             
  • White / Middle grey / Black
    
+         

+         

+             

+             
+         

+         

+             Switch to another electrode coordinates
+             file  
+         

+         

+             The link file can contain 
+                 
+                     more than one
+                     electrode coordinates file
+                 
+             . In this case, you can use any of
+             these models to show your data. F.ex. you can have a standard (and
+             smooth) model, plus the actual model (less smooth) of a given
+             subject, and switch from one to another. F.ex.:
+         

+         

+             
+         

+         

+             Potentials - Mouse
+         

+         

+             See the general mouse actions,
+             and especially the 
+                 brightness
+                 and contrast control
+              and the 
+                 polling
+                 function
+             .
+         

+         

+             Potentials - Menus
+         

+         

+             Search menu
+         

+         
    
+             
    
+                 Find TF with maximum value 
+             
    
+             
      
+                 
      
+                     Scan all Time Frames, and set the
+                     time cursor to the position where the greatest GFP is.
+                 
      
+             
    
+         

+         

+             Options menu
+         

+         
    
+             
    
+                 Interpolation
+             
    
+             
+             
    
+                 Specify a display scaling
+             
    
+             
      
+                 
      
+                     Ask the user for an arbitrary scaling value, equivalent to setting
+                     the brightness.
+                 
      
+             
    
+             
    
+                 Show / hide color scaling
+             
    
+             
      
+                 
      
+                     Does what it says.
+                 
      
+             
    
+             
    
+                 Show / hide projected axis and equator
+             
    
+             
      
+                 
      
+                     In 2D mode, this toggles on and off the
+                     display of the projected equator and axis.
+                 
      
+             
    
+             
    
+                 Show / hide orientation
+             
    
+             
      
+                 
      
+                     Does what it says.
+                 
      
+             
    
+             
    
+                 'Depth shifting' trick for 3D potentials
+             
    
+             
      
+                 
      
+                     If you apply some graphical links, the data are 3D consistents. That
+                     is, anything closer to the viewer will hide what is behind, as we get
+                     used to. In some cases, f.ex. depth electrodes, we wish to see
+                     their display even though they are hidden in the brain. So we can
+                     artificially shift the potentials closer to the viewer, and see them
+                     "on top" of the brain.
+                 
      
+                 
      
+                     Same as the 
+                         MRI Depth
+                         Shifting topic
+                     .
+                 
      
+                 
      
+                     F.ex. depth electrodes wihtout and with depth shifting:
+                 
      
+                 
      
+                     
+                 
      
+             
    
+         

+         

+             Potentials - Technical points
+         

+         

+             How do I get this display?
+         

+         

+             This display is actually automatically generated when enough
+             files have been linked together,
+             and therefore share enough informations together.
+         

+         

+             So, simply put at least these kind of files:
+         

+         
+         

+              
+         

+         

+             Putting many EEG files will display as many maps as there are
+             of EEGs, but putting many coordinates files does not. This
+             last case allows you to switch in real-time between different 3D models,
+             f.ex. between a real model from a subject, and an average one. All
+             the maps of the link being changed at once.
+         

+         

+              
+         

+         

+             Important points:
+         

+         
    
+             
  • 
+                 
    
+                     Putting many EEG files will display as many maps as there are
+                     of files.
+                 
    
+             
  • 
+                 
    
+                     You can put many coordinates files, but only one is active at a time.
+                 
    
+             
  • 
+                 
    
+                     
+                         You have to sure the sequence of the electrodes in the coordinates
+                         file exactly match the sequence of the tracks in the EEG files
+                     .
+                     Missing this point leads to totally erroneous results and displays!
+                 
    
+             
  • 
+                 
    
+                     Cartool is doing a lot of checkings to ensure you are on the safe
+                     side of this elaborate display. Though, only you can assert that all
+                     these files match together (the solution points with the MRI space
+                     and the IS matrix).
+                 
    
+         

+         

+              
+         

+         

+             Recommended readings: the fabulous 
+                 
+                     Linking
+                     Files
+                 
+              story, as well as the infamous "
+                 
+                     windows
+                     in slavery
+                 
+             ".
+         

+         

+             ROIs and potentials display
+         

+         

+             Well, there is no direct control / button for ROIs in the potential
+             display. This is done through the usual ones, and from the 
+                 EEG
+                 tracks ROI controls
+             .
+         

+         

+             So, if the EEG display is in ROIs mode,
+             showing the tracks on top will show the 
+                 tracks
+                 grouped by roi
+             , with the underlying map unchanged:
+         

+         

+             
+         

+         

+             Now, if the rois are averaged,
+             then the averaged tracks are shown, and the underlying 
+                 map shows
+                 the averaged values
+             , too (the electrodes not within a roi are set
+             to zero):
+         

+         

+             
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+     

  
 
\ No newline at end of file
diff --git a/docs/ReferenceGuide/problems-resolution.html b/docs/ReferenceGuide/problems-resolution.html
index 61762d1d..7c1e380c 100644
--- a/docs/ReferenceGuide/problems-resolution.html
+++ b/docs/ReferenceGuide/problems-resolution.html
@@ -2,168 +2,216 @@
  
   Appendixes A - Problems Resolution
  
- 
-  

-   Appendix A

-   Problems Resolution

-  

-    

-  

-   Graphics problems

-   General problems

-  

-   Graphics problems

-  

-   Corrupted display of any sort:

-  
    
-   
  • 
-   
    
-    Check the driver of your graphic card, and update it before 
-    trying anything else. This is the major cause for erratic behaviors.
    
-   
  • 
-   
    
-    Check again for the latest driver!
    
-   
  • 
-   
    
-    Go in the advanced properties of the Display, and remove all 
-    accelerations. Run again Cartool, if it works, the problem is 
-    definitely on the graphic card side! (see points 1 and 2).
    
-   
  • 
-   
    
-    The graphic card has to be OpenGL 
-    compliant, but even if it says so, each manufacturer has its own 
-    interpretation of the standard. So try to tune the display setting in 
-    the advanced properties. Usually, I recommend setting things for 
-    "Fast" rather than "Quality" performances, or 
-    something like "Application preferences".
    
-   
  • 
-   
    
-    Still it may not work properly, although it works on other computers, 
-    then you really have a problem! Either wait for the next driver 
-    (points 1, 2, 3), especially if you card is brand new. Or you simply 
-    need to change the graphic card, and  it is worth putting a 
-    little extra money on it. The more it accelerates features by 
-    hardware, the better. You can also keep the card when 
-    upgrading/changing your PC.
    
-   
  • 
-   
    
-    If you don't have an accelerated card, that means you rely on the 
-    software library provided in Windows (opengl32.dll). It does 
-    behave strangely with demanding applications like Cartool, and 
-    especially if you are running short of memory. I can't do anything 
-    for you, apart from telling you again to buy a graphic card.
    
-   

-  

-   The display is slow:

-  
    
-   
  • 
-   
    
-    In Cartool, go in Help|About,
-     and see if Cartool recognizes the graphic adapter. If not, it may 
-    not be installed correctly (drivers...) or it may be turned off 
-    (display settings again).
    
-   
  • 
-   
    
-    Try to tune up the properties of the OpenGL. It may change from card 
-    to card, but try to remove any anti-aliasing, and select for speed, 
-    not quality.
    
-   

-  

-   It doesn't print correctly:

-  

-   Cartool is not really tuned for printing, though it has the ability. 
-   Unfortunately, the Microsoft implementation of OpenGL is known to be 
-   buggy, and can not print correctly. To bypass this, do some "copy
-    as bitmaps" and paste in some application, then print. Sorry, 
-   that's all for now, I will fix this later.

-  

-   

-     

-   

-  

-   General problems

-  

-   The program is so slow...

-  
    
-   
  • 
-   
    
-    Make sure you are using the 64bit edition of Cartool, which is highly 
-	optimized for speed, and not some old 32bit version.
    
-	  
  • 
-      
    
-    You must have enough memory to avoid as much as possible memory 
-    swapping on the disk. The more the memory, the better, especially if 
-    you work with big volumes. Minimum is 512M, I'd say, 1G is fine for now.
    
-   
  • 
-   
    
-    Try to optimize the swap file (known as page file in windows), 
-    either with some third party utility, or using the following trick. 
-    Set page file to 0 (control panel / system / advanced / performance 
-    options), ignoring warning messages, reboot, then defrag your disk. 
-    Set back the page file to its original amount, reboot again. This 
-    will provide a fresh, unfragmented page file, which can really boost 
-    your machine again!
    
-   
  • 
-   
    
-    It may not be very efficient to have multiple instances of Cartool 
-    running at the same time, though it works.
    
-   

-  

-   The program crashes immediately when started

-  

-   Presently, you must have Administrator rights to run Cartool, because 
-   it updates the Windows registry. If it is not the case, try this. Do 
-   a shortcut to Cartool.exe on the desktop, and edit its properties. In 
-   the Target field, after the Cartool.exe, add /noregister to 
-   avoid touching the registry. Then use this shortcut to launch 
-   Cartool. Note that Cartool has to be run at least once as an 
-   Administrator to create the file associations for Windows.

-  

-   The Explorer can not open anymore the files when double-clicking

-  

-   Cartool registers all its known file extensions to Windows, and each 
-   time it is run. If you happen to have multiple versions of Cartool on 
-   your machine, then each version tries to steal the registry for 
-   itself at each run time. You finish with a real mess, and 
-   double-clicking may open an unexpected version of Cartool (therefor 
-   leading to some misunderstandings and/or errors), or simply does not 
-   work anymore. Open the correct Cartool version, then reset
-    the registry.

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    
+ 
+     

+         

+             Appendix A

+             Problems Resolution
+         

+         

+              
+         

+         

+             Graphics problems

+             General problems
+         

+         

+             Graphics problems
+         

+         

+             Corrupted display of any sort:
+         

+         
    
+             
  • 
+                 
    
+                     Check the driver of your graphic card, and update it before
+                     trying anything else. This is the major cause for erratic behaviors.
+                 
    
+             
  • 
+                 
    
+                     Check again for the latest driver!
+                 
    
+             
  • 
+                 
    
+                     Go in the advanced properties of the Display, and remove all
+                     accelerations. Run again Cartool, if it works, the problem is
+                     definitely on the graphic card side! (see points 1 and 2).
+                 
    
+             
  • 
+                 
    
+                     The graphic card has to be OpenGL
+                     compliant, but even if it says so, each manufacturer has its own
+                     interpretation of the standard. So try to tune the display setting in
+                     the advanced properties. Usually, I recommend setting things for
+                     "Fast" rather than "Quality" performances, or
+                     something like "Application preferences".
+                 
    
+             
  • 
+                 
    
+                     Still it may not work properly, although it works on other computers,
+                     then you really have a problem! Either wait for the next driver
+                     (points 1, 2, 3), especially if you card is brand new. Or you simply
+                     need to change the graphic card, and  it is worth putting a
+                     little extra money on it. The more it accelerates features by
+                     hardware, the better. You can also keep the card when
+                     upgrading/changing your PC.
+                 
    
+             
  • 
+                 
    
+                     If you don't have an accelerated card, that means you rely on the
+                     software library provided in Windows (opengl32.dll). It does
+                     behave strangely with demanding applications like Cartool, and
+                     especially if you are running short of memory. I can't do anything
+                     for you, apart from telling you again to buy a graphic card.
+                 
    
+         

+         

+             The display is slow:
+         

+         
    
+             
  • 
+                 
    
+                     In Cartool, go in Help|About,
+                     and see if Cartool recognizes the graphic adapter. If not, it may
+                     not be installed correctly (drivers...) or it may be turned off
+                     (display settings again).
+                 
    
+             
  • 
+                 
    
+                     Try to tune up the properties of the OpenGL. It may change from card
+                     to card, but try to remove any anti-aliasing, and select for speed,
+                     not quality.
+                 
    
+         

+         

+             It doesn't print correctly:
+         

+         

+             Cartool is not really tuned for printing, though it has the ability.
+             Unfortunately, the Microsoft implementation of OpenGL is known to be
+             buggy, and can not print correctly. To bypass this, do some "copy
+             as bitmaps" and paste in some application, then print. Sorry,
+             that's all for now, I will fix this later.
+         

+         

+             

+                  
+             

+         

+         

+             General problems
+         

+         

+             The program is so slow...
+         

+         
    
+             
  • 
+                 
    
+                     Make sure you are using the 64bit edition of Cartool, which is highly
+                     optimized for speed, and not some old 32bit version.
+                 
    
+             
  • 
+                 
    
+                     You must have enough memory to avoid as much as possible memory
+                     swapping on the disk. The more the memory, the better, especially if
+                     you work with big volumes. Minimum is 512M, I'd say, 1G is fine for now.
+                 
    
+             
  • 
+                 
    
+                     Try to optimize the swap file (known as page file in windows),
+                     either with some third party utility, or using the following trick.
+                     Set page file to 0 (control panel / system / advanced / performance
+                     options), ignoring warning messages, reboot, then defrag your disk.
+                     Set back the page file to its original amount, reboot again. This
+                     will provide a fresh, unfragmented page file, which can really boost
+                     your machine again!
+                 
    
+             
  • 
+                 
    
+                     It may not be very efficient to have multiple instances of Cartool
+                     running at the same time, though it works.
+                 
    
+         

+         

+             The program crashes immediately when started
+         

+         

+             Presently, you must have Administrator rights to run Cartool, because
+             it updates the Windows registry. If it is not the case, try this. Do
+             a shortcut to Cartool.exe on the desktop, and edit its properties. In
+             the Target field, after the Cartool.exe, add /noregister to
+             avoid touching the registry. Then use this shortcut to launch
+             Cartool. Note that Cartool has to be run at least once as an
+             Administrator to create the file associations for Windows.
+         

+         

+             The Explorer can not open anymore the files when double-clicking
+         

+         

+             Cartool registers all its known file extensions to Windows, and each
+             time it is run. If you happen to have multiple versions of Cartool on
+             your machine, then each version tries to steal the registry for
+             itself at each run time. You finish with a real mess, and
+             double-clicking may open an unexpected version of Cartool (therefor
+             leading to some misunderstandings and/or errors), or simply does not
+             work anymore. Open the correct Cartool version, then 
+                 reset
+                 the registry
+             .
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+     

  
 
\ No newline at end of file
diff --git a/docs/ReferenceGuide/reprocess-tracks.html b/docs/ReferenceGuide/reprocess-tracks.html
index 925f51de..30b16566 100644
--- a/docs/ReferenceGuide/reprocess-tracks.html
+++ b/docs/ReferenceGuide/reprocess-tracks.html
@@ -2,962 +2,1284 @@
  
   Reprocess / Export Tracks
  
- 
-  

-   Reprocess / Export Tracks

-  

-    

-  

-   What is Reprocess / Export Tracks?

-   Running from the Dialog

-   Running from the Command-Line Interface (CLI)
Results

-   Technical points and hints
   
-   Sequence of Processing
   
-   Temporal Filtering
   
-   Spatial Filtering and Adding Null Track
   
-   ROIs
    
-   Specifying list of tracks
   
-   Exporting Computed Tracks

-  

-   What is Reprocess / Export Tracks?

-  

-   This is a versatile tool to read EEG files (or other 
-   tracks-like files), then export them to some new files after 
-   applying some basic transformations. They include things such as:

-  
    
-   
  • 
-   
    
-    Cropping the time line,
    
-    
  • Saving only a subset of tracks, possibliy 
-	re-orering them,
    
-    
  • Tracks filtering (Butterworth, Notches, 
-	Spatial Filter etc..),
    
-    
  • Baseline correction,
    
-    
  • Re-referencing,
    
-    
  • Rescaling / normalizing,
    
-    
  • Downsampling,
    
-    
  • Changing file format,
  • 
-	  Applying Region Of Interests (ROIs)
    
-    
  • etc...
    
-   

-  

-    

-  

-   Input files can be anything that looks like tracks:

-  
-  

-    

-  

-   See here what the ouput files 
-   can be, plus the special case of 
-   frequency files.

-  

-   Running from the Dialog

-  

-   Call the dialog from Tools
-    | Export tracks menu, which is context sensitive:

-  
    
-   
  • 
-   
    
-    Called from an EEG file, the 
-    processing will apply only to this file.
    
-   
  • 
-   
    
-    In any other case, the dialog will 
-    operate in Batch mode, requiring you to later select some files.
    
-   

-  

-    

-  

-   The following dialog pops out. Fill the parameters which are relevant 
-   for you, then click either on Process Current or Batch Process 
-   (according to how the dialog was invoked):

-  

-   

-    

-   

-  

-   
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-       
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-       
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-       
-     
-     
-       
-    
-     
-     
-    
-       
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-       
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-       
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-   

-      

-       Tracks or ROIs

-      

-        

-      

-       Tracks

-      

-       From an opened EEG:

-       Prefilled with the current selected 
-       tracks, otherwise with the current displayed tracks.

-      

-       In Batch Mode:

-       On first call, default is *, meaning all regular
-        tracks.

-      

-       You can of course modify this list. See 
-       important note below about notation.

-      

-       Names from XYZ:

-      

-       Optionally pointing to a file with the electrodes
-        coordinates and names. The names of the electrodes are taken 
-       from this file, overriding the original names from the EEG (i.e. 
-       you can rename the electrodes).

-       Be careful that the list above respect these names, otherwise you 
-       will get an error message.

-      

-       Constraints as in the link
-        mechanism must be respected, such as same number of electrodes, 
-       same order, etc...

-      

-       ROIs

-      

-       The ROIs to be used in the export.

-      

-       Note 1: The ROIs option and the Tracks field above are mutually exclusive.

-       Note 2: The ROIs option and the Add Null 
-	   Tracks below are also mutually 
-	   exclusive.

-      

-       Input Time

-      

-        

-      

-       Interval

-      

-       Export a time interval, specified in time
-        frames.

-      

-       From

-      

-       First time frame to be exported.

-      

-       to

-      

-       Last time frame to be exported.

-      

-       End of File

-      

-       Automatically set the last time frame to export to the actual end 
-       of the current file. Useful in Batch Mode,
-        if the files have different lengths.

-      

-       Triggers To Keep

-      

-       Only the time frames contained in the specified list of triggers / markers 
-       will be exported.

-      

-       Triggers To Exclude

-      

-       Only the time frames excluded from the specified list of triggers / markers 
-       will be exported.

-      

-       Processing Parameters

-      

-        

-      

-       Appending Null Track(s):

-      

-       A list of track name(s) that will be appended after the last input 
-	   tracks. Its/their values will be set to 0.

-       The intent is to add a single reference track that was not included in 
-	   the recording file, though you might go beyond this and add as many 
-	   tracks as you wish.

-       Note: Appending Null Tracks and applying ROIs are mutually exclusive.

-      

-       Filters:

-      

-       Also see these notes about:

-		

-      

-       No Filters

-      

-       No filtering at all, just using the raw data from the file.

-      

-       Use Current Filters

-      

-       Using the filters currently set in the current opened EEG. Useful as a 
-	   kind of "Save what I see" feature.

-       Note: If user has added null tracks,
-	   these tracks will also be filtered.

-      

-       Other Filters

-      

-       Using these specific filters, bypassing any filters that might be in 
-	   current use. This will pop out the usual Filter Dialog 
-	   for you to fill the relevant filters parameters.

-      

-       Note 1: You might have to fill the Sampling Frequency entry of this dialog, 
-	   though.

-       Note 2: If user has added null tracks,
-	   these tracks will also be filtered.

-      

-       Reference:

-      

-       Also see this note about the Sequence of 
-	   Processing.

-      

-       No Reference

-      

-       Use the same reference as when the file(s) was(were) written, that 
-       is, no change in reference.

-      

-       Use Current Reference

-      

-       Use the reference currently in use. Useful only if the files have 
-       already been opened in Cartool, and the user has changed the reference.

-      

-       Average Reference

-      

-       Use the average reference, 
-       overriding current reference.

-       Note: If user has added null tracks,
-	   these tracks will be included in the new average reference 
-	   computation.

-      

-       Other Reference

-      

-       Use the average of the specified list of electrodes. If only 
-       one electrode is specified, this will be the reference.

-       Note: If user has added null tracks,
-	   these tracks can also be used as reference.

-      

-       Baseline Correction:

-      

-        

-      

-       Apply Baseline Correction

-      

-       Select this to apply some baseline correction (subtracting each track 
-       with its average within a given time period).

-       Note: If user has added null tracks,
-	   these tracks will also have be baseline-corrected.

-      

-       From

-      

-       First time frame of the baseline.

-      

-       This is an absolute value, not a relative one, and 
-       should be within the range of available time frames. Otherwise it 
-       will be clipped to these limits.

-      

-       to

-      

-       Last time frame of the baseline.

-      

-       This is an absolute value, not a relative one, and 
-       should be within the range of available time frames. Otherwise it 
-       will be clipped to these limits.

-      

-       The limits specified need not to be within the range of 
-       the time period exported. They can be whatever you wish, 
-       Cartool will handle all the cases gracefully.

-      

-       End of File

-      

-       Automatically set the last time frame of the baseline correction to 
-       the actual end of the current file. Useful in Batch
-        Mode, if the files have different lengths.

-      

-       Rescaling:

-      

-       Note: If user has added null tracks,
-	   these tracks will also be rescaled.

-      

-       No Rescaling

-      

-       What is says.

-      

-       Rescaled By

-      

-       Rescale the EEG values by multiplying with the provided value. 
-       Negative factors are allowed to perform a polarity inversion.

-      

-       GFP Normalize

-      

-       For each EEG, compute the mean GFP (or RMS) over the selected time period,
-        then divide the EEG values with it.

-      

-       See this point on 
-       positive data and also this point.

-      

-       Output Time

-      

-        

-      

-       Output Time is:

-      

-        

-      

-       Sequential

-      

-       The input time period, once processed, is outputted sequentially.

-      

-       F.ex. if the input time range selected is from 100 to 149 time 
-       frames, then the resulting output will be 50 time frames long.

-      

-       Average

-      

-       The input time period, once processed, is averaged, and 
-       a single value is outputted.

-      

-       F.ex. if the input time range selected is from 100 to 149 time 
-       frames, then the resulting output will be 1 time frame long.

-      

-       Time Downsampling:

-      

-        

-      

-       Downsample by Integer Ratio:

-      

-       Downsample the data by the specified integer ratio (>1). 
-       The resulting sampling frequency will be the original one divided by 
-       this ratio.

-      

-       The method used is equivalent to a CIC (Cascaded 
-       Integrator-Comb) filter, followed by a light High Pass FIR 
-       (compensation) filter, and finally the decimation itself.

-      

-        

-      

-       Also note that downsampling is disabled in the following cases:

-      
    
-       
  • 
-       
    
-        Input Time Period is taken from Triggers
    
-       
  • 
-       
    
-        Averaging the output value

-      

-       Output File

-      

-        

-      

-       Filename Infix 

-      

-       The exported filenames will have these characters inserted. Default 
-       is "Export".

-      

-       Output File Type

-      

-       A drop-down list with currently the following available types:

-      

-       TXT (text)

-      

-       Text file, actually the same as the .ep file 
-	   except for the extension.

-      

-       EP (text)

-      

-       Text file, basically a plain matrix of data. See the .ep file specification.

-      

-       EPH (text)

-      

-       Text file, basically the same as the .ep above 
-	   but with an additional header line. See the .eph file specification.

-      

-       SEF (binary)

-      

-       Binary file, see the .sef file specification.

-      

-       Useful when exporting original recording file(s), or to include the 
-       electodes / ROIs names in the new file(s).

-      

-       EEG (binary)

-      

-       Binary file, file format from 
-	   BrainVision. This is the default option as it is a quite 
-	   versatile format.

-		   

-      

-       EDF (binary)

-      

-       Binary file, see the .edf file specification.

-      

-       Useful only for data interchange, otherwise don't use (loss of precision)!

-      

-       RIS (binary)

-      

-       Binary file, see the .ris file specification.

-      

-       Used mainly if you are already testing other .ris 
-       files, and want to visualize the results in 3D.

-      

-       Options

-      

-        

-      

-       Export Underlying Markers

-      

-       Also exports the markers belonging to the selected time period, 
-       creating a .mrk file

-      

-       Open File(s) Upon Completion

-      

-       ...of the exportation. Just be careful in Batch
-        Mode, this could open a lot of files (read: crash)! (the 
-       original EEG files are opened one at a time, then closed when done).

-      

-       Concatenate all into 1 File

-      

-       If you have Batch Process a list of files, then the results will be 
-	   concatenated into a single output file. Note that this happanes as the 
-	   last step of the Reprocess Tracks, so what is appended depends on the 
-	   parameters chosen above!

-       Markers will be conveniently added at each starting point of the original 
-	   files.

-      

-       Process Current

-      

-       Enabled when called from an EEG window, the 
-       exportation will apply to this file only.

-      

-        

-      

-       This button remains disabled until all the parameter 
-       dialogs have received enough (and consistent) informations. If 
-       this is not the case, first check the current dialog: if its 
-       "Next" button is disabled, the problem is in the current 
-       dialog. Otherwise, browse the other dialogs for some missing informations.

-      

-       Batch Process

-      

-       Enabled when not called from an EEG window:

-      
    
-       
  • 
-       
    
-        Clicking this button will open a dialog from which you can select a set
-         of files, within a single directory.
    
-       
  • 
-       
    
-        Using Drag & Drop, you can drop files in the dialog and 
-        process them directly. Plus, it allows you to pick files from 
-        different directories, if you can select them through a handy 
-        utility like Everything beforehand.
    
-       

-      

-        

-      

-       This button remains disabled until all the parameter 
-       dialogs have received enough (and consistent) informations. If 
-       this is not the case, first check the current dialog: if its 
-       "Next" button is disabled, the problem is in the current 
-       dialog. Otherwise, browse the other dialogs for some missing informations.

-      

-       Cancel

-      

-       Quit the dialog.

-      

-       Help

-      

-       Launch the Help to the right page (should land on this page...).

-  

-   Runnning from the Command-Line Interface (CLI)

-  

-   You can call the Reprocess toolbox directly from the command-line, see the
-   full syntax and examples 
-   here.

-  

-   Results

-  
    
-   
  • 
-   
    
-    Exported files are written in the same directories as their sources.
-     File names are inserted with the infix string, which is by 
-    default "Export", followed by the appropriate file extension.
    
-   
  • 
-   
    
-    In case the input is a Freq
-     file, each of the stored frequency will be output in a 
-    separate file. The resulting filenames will include which 
-    frequency has been used, f.ex.  "MyFile.4-8 Hz.EP", 
-    "MyFile.8-14 Hz.EP", "MyFile.14-20 Hz.EP".
    
-   
  • 
-   
    
-    Verbose file .vrb 
-    (text), showing all the parameters.
    
-   

-  

-   Technical points and hints

-  

-   Sequence of Processing

-  

-   The various available processing follow a very precise sequence, 
-   which is:

-  
    
-   
  • 
-   
    
-    Reading the raw tracks from file
  • 
-      
    
-      Cropping the time-line (interval, keeping triggers, or excluding triggers)
  • 
-      
    
-      Appending null track(s). All the following steps will make use of 
-	  these new tracks!
    
-    
  • Filtering (pre-reference)
      
-		
    • DC / Baseline
    • Butterworth High-Pass / 
-		Low-Pass / Band-Pass
    • Notches
    • Spatial 
-		Filter
    • Ranking
    
-    
  • Re-referencing
  • Filtering (post-reference)
      
-		  
    • Rectification
    • Envelope
    • 
-		  Thresholding Above and/or Below
    
-    
  • Baseline correction
    
-    
  • Rescaling
    
-    
  • Averaging the whole time range or Downsampling
    
-    
  • Computing ROIs
    
-   

-  

-   Temporal
-   Filtering

-  

-   Cartool uses a classic sliding window method, which is 
-   mandatory to avoid artifacts, especially with high-pass filter:

-  
    
-   
  • 
-   
    
-    to export time frame t, read data between t - filtersize 
-    and t + filtersize
    
-   
  • 
-   
    
-    filter, correct, etc...
    
-   
  • 
-   
    
-    save only the time frame value at t
    
-   
  • 
-   
    
-    repeat for all time frames
    
-   

-  

-    

-  

-   As a consequence, Cartool reads / filters / processes way more points 
-   than are actually written to file. This is the only way to ensure the 
-   results are correct, so be patient, it has to be done only once after all...

-  

-   filtersize depends on the sampling frequency of the 
-   current file. The higher the sampling frequency, the bigger the filtersize 
-   variable, the longer the computation.

-  

-   Spatial
-   Filtering and Adding Null Track

-  

-   The Spatial Filter depends on a
-   .xyz coordinates 
-   file to operate, as it needs the spatial locations of each and every 
-   electrodes. It is also requires that the number of tracks in the EEG 
-   file and the number of electrodes in the .xyz file 
-   be exactly the same. Cartool enforces that for you all the time, so 
-   nothing to worry here.

-  

-   However, in case the user required for an 
-   additional null track, the EEG has suddenly one more dimension. To 
-   properly apply any Spatial Filter, the user should then select the
-   Other Filter option, and drop a correct .xyz 
-   file with an additional electrode, too. This way both EEG and electrodes 
-   coordinates dimensions will match again.

-  

-   In case of mismatch, Cartool will likely complain, skip the Spatial 
-   Filter step(!), and add an error message in the .vrb  
-    verbose file...

-  

-   ROIs

-  

-   If a .rois file 
-   has been provided (see Creating ROIs),
-    all members of a given roi are averaged together as a final step. 
-   Then only the averaged value is written to file.

-  

-   If you intend to do some stats later on these roi-ed files, think twice!
-    In fact, it is a far better practice to not compute the rois 
-   yourself (for the stats), but let the Statistics
-    processing do it for you. The main problem being that data 
-   normalization that will be wrong, as the original data will be lost, 
-   so will be the original GFP. Plus, why fill your drive with another 
-   set of files?

-  

-   But if you just want ROIs for some display purpose, or re-ordering 
-   your tracks, just proceed!

-  

-    

-  

-   Noteworthy is a side-effect of Exporting with ROIs, which is 
-   the re-ordering of the tracks that occurs. Within each roi, 
-   all tracks will follow the exact sequence given in the .rois file.
-    See an example, first the original order, then one roi with a 
-   quarter of the electrodes:

-  

-   

-  

-   Specifying the list of tracks

-  

-   You can:

-  
    
-   
  • 
-   
    
-    Enumerate the tracks one by one: e1 e2 e3
    
-   
    
-    The order is relevant, this is not equivalent to e2 e3 e1!
    
-    Use whatever separator you like: comma, semi-colon, space, tab.
    
-   
  • 
-   
    
-    Use interval notation: e1-e20
    
-   
    
-    Which means all tracks from e1 up to e20, both 
-    included, and in the order found in the file.
    
-   
  • 
-   
    
-    You can of crouse combine the two notations: e3 e5 e10-e20
    
-   

-  

-    

-  

-   With interval notation, the ordering is the one found in the file you 
-   are processing, and is by no mean lexicographic (à la 
-   dictionary). So in this example C1-C2 means C1, Cz, C2; 
-   and T3-T4 means T3, C3, C1, Cz, C2, C4, T4:

-  

-   

-  

-   Exporting Computed Tracks

-  

-   You can export the computed tracks by 
-   using any of the following predefined names:

-  
    
-   
  • 
-   
    
-    GFP  for the Global Field Power, if data are signed.
    
-    
  • RMS for the Root Mean Square, instead of the 
-    GFP if data are positive.
    
-    
  • DIS  for the dissimilarity.
    
-    
  • AVG  for the average.
    
-   

-  

-   Exporting frequency files

-  

-   See the Results paragraph.

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    
+ 
+     

+         

+             Reprocess / Export Tracks
+         

+         

+              
+         

+         

+             What is Reprocess / Export Tracks?

+             Running from the Dialog

+             Running from the Command-Line Interface (CLI)
Results

+             Technical points and hints
   
+             Sequence of Processing
   
+             Temporal Filtering
   
+             Spatial Filtering and Adding Null Track
   
+             ROIs
    
+                 Specifying list of tracks
+             
   
+             Exporting Computed Tracks
+         

+         

+             What is Reprocess / Export Tracks?
+         

+         

+             This is a versatile tool to read EEG files (or other
+             tracks-like files), then 
+                 export them to some new files after
+                 applying some basic transformations
+             . They include things such as:
+         

+         
    
+             
  • 
+                 
    
+                     Cropping the time line,
    
+             
  • 
+                 Saving only a subset of tracks, possibliy
+                 re-orering them,
    
+             
  • 
+                 Tracks filtering (Butterworth, Notches,
+                 Spatial Filter etc..),
    
+             
  • Baseline correction,
    
+             
  • Re-referencing,
    
+             
  • Rescaling / normalizing,
    
+             
  • Downsampling,
    
+             
  • Changing file format,
+             
  • 
+                 Applying Region Of Interests (ROIs)
    
+             
  • etc...
    
+         

+         

+              
+         

+         

+             Input files can be anything that looks like tracks:
+         

+         
+         

+              
+         

+         

+             See here what the ouput files
+             can be, plus the 
+                 special case of
+                 frequency files
+             .
+         

+         

+             Running from the Dialog
+         

+         

+             Call the dialog from 
+                 
+                     Tools
+                     | Export tracks
+                 
+              menu, which is context sensitive:
+         

+         
    
+             
  • 
+                 
    
+                     Called from an EEG file, the
+                     processing will apply only to this file.
+                 
    
+             
  • 
+                 
    
+                     In any other case, the dialog will
+                     operate in Batch mode, requiring you to later select some files.
+                 
    
+         

+         

+              
+         

+         

+             The following dialog pops out. Fill the parameters which are relevant
+             for you, then click either on Process Current or Batch Process
+             (according to how the dialog was invoked):
+         

+         

+             

+                 
+             

+         

+         

+             
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+             

+                         

+                             Tracks or ROIs
+                     

+                         

+                              
+                     

+                         

+                             Tracks
+                     

+                         

+                             From an opened EEG:

+                             Prefilled with the current selected
+                             tracks, otherwise with the current displayed tracks.
+                         

+                         

+                             In Batch Mode:

+                             On first call, default is *, meaning all 
+                                 regular
+                                 tracks
+                             .
+                         

+                         

+                             You can of course modify this list. 
+                                 See
+                                 important note below about notation
+                             .
+                     

+                         

+                             Names from XYZ:
+                     

+                         

+                             Optionally pointing to a file with the 
+                                 electrodes
+                                 coordinates
+                              and names. The 
+                                 names of the electrodes are taken
+                                 from this file
+                             , overriding the original names from the EEG (i.e.
+                             you can rename the electrodes).

+                             Be careful that the list above respect these names, otherwise you
+                             will get an error message.
+                         

+                         

+                             Constraints as in the 
+                                 link
+                                 mechanism
+                              must be respected, such as same number of electrodes,
+                             same order, etc...
+                     

+                         

+                             ROIs
+                     

+                         

+                             The ROIs to be used in the export.
+                         

+                         

+                             Note 1: The ROIs option and the Tracks field above are mutually exclusive.
+                         

+                             Note 2: The ROIs option and the 
+                                 Add Null
+                                 Tracks
+                              below are also mutually
+                             exclusive.
+                     

+                         

+                             Input Time
+                     

+                         

+                              
+                     

+                         

+                             Interval
+                     

+                         

+                             Export a time interval, specified in 
+                                 time
+                                 frames
+                             .
+                     

+                         

+                             From
+                     

+                         

+                             First time frame to be exported.
+                     

+                         

+                             to
+                     

+                         

+                             Last time frame to be exported.
+                     

+                         

+                             End of File
+                     

+                         

+                             Automatically set the last time frame to export to the 
+                                 actual end
+                                 of the current file
+                             . Useful in Batch Mode,
+                             if the files have different lengths.
+                     

+                         

+                             Triggers To Keep
+                     

+                         

+                             Only the time frames contained in the specified list of triggers / markers
+                             will be exported.
+                     

+                         

+                             Triggers To Exclude
+                     

+                         

+                             Only the time frames excluded from the specified list of triggers / markers
+                             will be exported.
+                     

+                         

+                             Processing Parameters
+                     

+                         

+                              
+                     

+                         

+                             Appending Null Track(s):
+                     

+                         

+                             A list of track name(s) that will be appended after the last input
+                             tracks. Its/their values will be set to 0.
+                         

+                             The intent is to add a single reference track that was not included in
+                             the recording file, though you might go beyond this and add as many
+                             tracks as you wish.
+                         

+                             Note: Appending Null Tracks and applying ROIs are mutually exclusive.
+                     

+                         

+                             Filters:
+                     

+                         

+                             Also see these notes about:

+                     

+                         

+                             No Filters
+                     

+                         

+                             No filtering at all, just using the raw data from the file.
+                     

+                         

+                             Use Current Filters
+                     

+                         

+                             Using the filters currently set in the current opened EEG. Useful as a
+                             kind of "Save what I see" feature.
+                         

+                             Note: If user has added null tracks,
+                             these tracks will also be filtered.
+                     

+                         

+                             Other Filters
+                     

+                         

+                             Using these specific filters, bypassing any filters that might be in
+                             current use. This will pop out the usual Filter Dialog
+                             for you to fill the relevant filters parameters.
+                         

+                         

+                             Note 1: You might have to fill the Sampling Frequency entry of this dialog,
+                             though.
+                         

+                             Note 2: If user has added null tracks,
+                             these tracks will also be filtered.
+                     

+                         

+                             Reference:
+                     

+                         

+                             Also see this note about the 
+                                 Sequence of
+                                 Processing
+                             .
+                     

+                         

+                             No Reference
+                     

+                         

+                             Use the same reference as when the file(s) was(were) written, that
+                             is, no change in reference.
+                     

+                         

+                             Use Current Reference
+                     

+                         

+                             Use the reference currently in use. Useful only if the files have
+                             already been opened in Cartool, and the user has changed the reference.
+                     

+                         

+                             Average Reference
+                     

+                         

+                             Use the average reference,
+                             overriding current reference.
+                         

+                             Note: If user has added null tracks,
+                             
+                                 these tracks will be included in the new average reference
+                                 computation
+                             .
+                     

+                         

+                             Other Reference
+                     

+                         

+                             Use the average of the specified list of electrodes. If only
+                             one electrode is specified, this will be the reference.
+                         

+                             Note: If user has added null tracks,
+                             these tracks can also be used as reference.
+                     

+                         

+                             Baseline Correction:
+                     

+                         

+                              
+                     

+                         

+                             Apply Baseline Correction
+                     

+                         

+                             Select this to apply some baseline correction (subtracting each track
+                             with its average within a given time period).
+                         

+                             Note: If user has added null tracks,
+                             these tracks will also have be baseline-corrected.
+                     

+                         

+                             From
+                     

+                         

+                             First time frame of the baseline.
+                         

+                         

+                             This is an absolute value, not a relative one, and
+                             should be within the range of available time frames. Otherwise it
+                             will be clipped to these limits.
+                     

+                         

+                             to
+                     

+                         

+                             Last time frame of the baseline.
+                         

+                         

+                             This is an absolute value, not a relative one, and
+                             should be within the range of available time frames. Otherwise it
+                             will be clipped to these limits.
+                         

+                         

+                             The limits specified need not to be within the range of
+                             the time period exported. They can be whatever you wish,
+                             Cartool will handle all the cases gracefully.
+                     

+                         

+                             End of File
+                     

+                         

+                             Automatically set the last time frame of the baseline correction to
+                             the actual end of the current file. Useful in 
+                                 Batch
+                                 Mode
+                             , if the files have different lengths.
+                     

+                         

+                             Rescaling:
+                     

+                         

+                             Note: If user has added null tracks,
+                             these tracks will also be rescaled.
+                     

+                         

+                             No Rescaling
+                     

+                         

+                             What is says.
+                     

+                         

+                             Rescaled By
+                     

+                         

+                             Rescale the EEG values by multiplying with the provided value.
+                             Negative factors are allowed to perform a polarity inversion.
+                     

+                         

+                             GFP Normalize
+                     

+                         

+                             For each EEG, compute the mean GFP (or RMS) over the selected time period,
+                             then divide the EEG values with it.
+                         

+                         

+                             See this 
+                                 point on
+                                 positive data
+                              and also this point.
+                     

+                         

+                             Output Time
+                     

+                         

+                              
+                     

+                         

+                             Output Time is:
+                     

+                         

+                              
+                     

+                         

+                             Sequential
+                     

+                         

+                             The input time period, once processed, is outputted sequentially.
+                         

+                         

+                             F.ex. if the input time range selected is from 100 to 149 time
+                             frames, then the resulting output will be 50 time frames long.
+                     

+                         

+                             Average
+                     

+                         

+                             The input time period, once processed, is averaged, and
+                             a single value is outputted.
+                         

+                         

+                             F.ex. if the input time range selected is from 100 to 149 time
+                             frames, then the resulting output will be 1 time frame long.
+                     

+                         

+                             Time Downsampling:
+                     

+                         

+                              
+                     

+                         

+                             Downsample by Integer Ratio:
+                     

+                         

+                             Downsample the data by the specified integer ratio (>1).
+                             The resulting sampling frequency will be the original one divided by
+                             this ratio.
+                         

+                         

+                             The method used is equivalent to a CIC (Cascaded
+                             Integrator-Comb) filter, followed by a light High Pass FIR
+                             (compensation) filter, and finally the decimation itself.
+                         

+                         

+                              
+                         

+                         

+                             Also note that downsampling is disabled in the following cases:
+                         

+                         
    
+                             
  • 
+                                 
    
+                                     Input Time Period is taken from Triggers
+                                 
    
+                             
  • 
+                                 
    
+                                     Averaging the output value
+                     

+                         

+                             Output File
+                     

+                         

+                              
+                     

+                         

+                             Filename Infix 
+                     

+                         

+                             The exported filenames will have these characters inserted. Default
+                             is "Export".
+                     

+                         

+                             Output File Type
+                     

+                         

+                             A drop-down list with currently the following available types:
+                     

+                         

+                             TXT (text)
+                     

+                         

+                             Text file, actually the same as the .ep file
+                             except for the extension.
+                     

+                         

+                             EP (text)
+                     

+                         

+                             Text file, basically a plain matrix of data. See the .ep file specification.
+                     

+                         

+                             EPH (text)
+                     

+                         

+                             Text file, basically the same as the .ep above
+                             but with an additional header line. See the .eph file specification.
+                     

+                         

+                             SEF (binary)
+                     

+                         

+                             Binary file, see the .sef file specification.
+                         

+                         

+                             Useful when exporting original recording file(s), or to include the
+                             electodes / ROIs names in the new file(s).
+                     

+                         

+                             EEG (binary)
+                     

+                         

+                             Binary file, 
+                                 file format from 
+                                     BrainVision
+                                 
+                             . This is the default option as it is a quite
+                             versatile format.
+                         

+                     

+                         

+                             EDF (binary)
+                     

+                         

+                             Binary file, see the .edf file specification.
+                         

+                         

+                             Useful only for data interchange, otherwise don't use (loss of precision)!
+                     

+                         

+                             RIS (binary)
+                     

+                         

+                             Binary file, see the .ris file specification.
+                         

+                         

+                             Used mainly if you are already testing other .ris
+                             files, and want to visualize the results in 3D.
+                     

+                         

+                             Options
+                     

+                         

+                              
+                     

+                         

+                             Export Underlying Markers
+                     

+                         

+                             Also exports the markers belonging to the selected time period,
+                             creating a .mrk file
+                     

+                         

+                             Open File(s) Upon Completion
+                     

+                         

+                             ...of the exportation. Just be careful in 
+                                 Batch
+                                 Mode
+                             , this could open a lot of files (read: crash)! (the
+                             original EEG files are opened one at a time, then closed when done).
+                     

+                         

+                             Concatenate all into 1 File
+                     

+                         

+                             If you have Batch Process a list of files, then the results will be
+                             concatenated into a single output file. Note that this happanes as the
+                             last step of the Reprocess Tracks, so what is appended depends on the
+                             parameters chosen above!
+                         

+                             Markers will be conveniently added at each starting point of the original
+                             files.
+                     

+                         

+                             Process Current
+                     

+                         

+                             Enabled when called from an EEG window, the
+                             exportation will apply to this file only.
+                         

+                         

+                              
+                         

+                         

+                             This button remains 
+                                 disabled until all the parameter
+                                 dialogs have received enough (and consistent) informations
+                             . If
+                             this is not the case, first check the current dialog: if its
+                             "Next" button is disabled, the problem is in the current
+                             dialog. Otherwise, browse the other dialogs for some missing informations.
+                     

+                         

+                             Batch Process
+                     

+                         

+                             Enabled when not called from an EEG window:
+                         

+                         
    
+                             
  • 
+                                 
    
+                                     Clicking this button will open a dialog from which you can select a 
+                                         set
+                                         of files
+                                     , within a single directory.
+                                 
    
+                             
  • 
+                                 
    
+                                     Using Drag & Drop, you can drop files in the dialog and
+                                     process them directly. Plus, it allows you to pick files 
+                                         from
+                                         different directories
+                                     , if you can select them through a handy
+                                     utility like Everything beforehand.
+                                 
    
+                         

+                         

+                              
+                         

+                         

+                             This button remains 
+                                 disabled until all the parameter
+                                 dialogs have received enough (and consistent) informations
+                             . If
+                             this is not the case, first check the current dialog: if its
+                             "Next" button is disabled, the problem is in the current
+                             dialog. Otherwise, browse the other dialogs for some missing informations.
+                     

+                         

+                             Cancel
+                     

+                         

+                             Quit the dialog.
+                     

+                         

+                             Help
+                     

+                         

+                             Launch the Help to the right page (should land on this page...).
+                     

+         

+         

+             Runnning from the Command-Line Interface (CLI)
+         

+         

+             You can call the Reprocess toolbox directly from the command-line, see the
+             
+                 
+                     full syntax and examples
+                     here
+                 
+             .
+         

+         

+             Results
+         

+         
    
+             
  • 
+                 
    
+                     Exported files are written in the same directories as their sources.
+                     File names are inserted with the infix string, which is by
+                     default "Export", followed by the appropriate file extension.
+                 
    
+             
  • 
+                 
    
+                     In case the input is a 
+                         Freq
+                         file
+                     , 
+                         each of the stored frequency will be output in a
+                         separate file
+                     . The resulting filenames will include which
+                     frequency has been used, f.ex.  "MyFile.4-8 Hz.EP",
+                     "MyFile.8-14 Hz.EP", "MyFile.14-20 Hz.EP".
+                 
    
+             
  • 
+                 
    
+                     Verbose file .vrb
+                     (text), showing all the parameters.
+                 
    
+         

+         

+             Technical points and hints
+         

+         

+             Sequence of Processing
+         

+         

+             The various available processing follow a very precise sequence,
+             which is:
+         

+         
    
+             
  • 
+                 
    
+                     Reading the raw tracks from file
+             
  • 
+                 
    
+                     Cropping the time-line (interval, keeping triggers, or excluding triggers)
+             
  • 
+                 
    
+                     Appending null track(s). 
+                         All the following steps will make use of
+                         these new tracks!
+                     
    
+             
  • 
+                 Filtering (pre-reference)
      
+                     
    • DC / Baseline
+                     
    • 
+                         Butterworth High-Pass /
+                         Low-Pass / Band-Pass
+                     
    • Notches
+                     
    • 
+                         Spatial
+                         Filter
+                     
    • Ranking
+                 
    
+             
  • Re-referencing
+             
  • 
+                 Filtering (post-reference)
      
+                     
    • Rectification
+                     
    • Envelope
+                     
    • 
+                         Thresholding Above and/or Below
+                 
    
+             
  • Baseline correction
    
+             
  • Rescaling
    
+             
  • Averaging the whole time range or Downsampling
    
+             
  • Computing ROIs
    
+         

+         

+             Temporal
+             Filtering
+         

+         

+             Cartool uses a classic sliding window method, which is
+             mandatory to avoid artifacts, especially with high-pass filter:
+         

+         
    
+             
  • 
+                 
    
+                     to export time frame t, read data between t - filtersize
+                     and t + filtersize
+                 
    
+             
  • 
+                 
    
+                     filter, correct, etc...
+                 
    
+             
  • 
+                 
    
+                     save only the time frame value at t
+                 
    
+             
  • 
+                 
    
+                     repeat for all time frames
+                 
    
+         

+         

+              
+         

+         

+             As a consequence, Cartool reads / filters / processes way more points
+             than are actually written to file. This is the only way to ensure the
+             results are correct, so be patient, it has to be done only once after all...
+         

+         

+             filtersize depends on the sampling frequency of the
+             current file. The higher the sampling frequency, the bigger the filtersize
+             variable, the longer the computation.
+         

+         

+             Spatial
+             Filtering and Adding Null Track
+         

+         

+             The Spatial Filter depends on a
+             
+                 .xyz coordinates
+                 file
+              to operate, as it needs the spatial locations of each and every
+             electrodes. It is also requires that 
+                 the number of tracks in the EEG
+                 file
+              and 
+                 the number of electrodes in the .xyz file
+                 be exactly the same
+             . Cartool enforces that for you all the time, so
+             nothing to worry here.
+         

+         

+             However, in case the user required for an 
+                 additional null track
+             , the EEG has suddenly one more dimension. To
+             properly apply any Spatial Filter, 
+                 the user should then select the
+                 Other Filter option
+             , and drop a correct .xyz
+             file with an additional electrode, too. This way both EEG and electrodes
+             coordinates dimensions will match again.
+         

+         

+             In case of mismatch, Cartool will likely complain, skip the Spatial
+             Filter step(!), and add an error message in the .vrb 
+             verbose file...
+         

+         

+             ROIs
+         

+         

+             If a .rois file
+             has been provided (see Creating ROIs),
+             all members of a given roi are averaged together as a final step.
+             Then only the averaged value is written to file.
+         

+         

+             If you intend to do some stats later on these roi-ed files, think twice!
+             In fact, it is a far better practice to not compute the rois
+             yourself (for the stats), but 
+                 let the 
+                     Statistics
+                     processing
+                  do it for you
+             . The main problem being that data
+             normalization that will be wrong, as the original data will be lost,
+             so will be the original GFP. Plus, why fill your drive with another
+             set of files?
+         

+         

+             But if you just want ROIs for some display purpose, or re-ordering
+             your tracks, just proceed!
+         

+         

+              
+         

+         

+             Noteworthy is a side-effect of Exporting with ROIs, which is
+             the re-ordering of the tracks that occurs. Within each roi,
+             all tracks will follow the exact sequence given in the .rois file.
+             See an example, first the original order, then one roi with a
+             quarter of the electrodes:
+         

+         

+             
+         

+         

+             Specifying the list of tracks
+         

+         

+             You can:
+         

+         
    
+             
  • 
+                 
    
+                     Enumerate the tracks one by one: e1 e2 e3
+                 
    
+                 
    
+                     The order is relevant, this is not equivalent to e2 e3 e1!
    
+                     Use whatever separator you like: comma, semi-colon, space, tab.
+                 
    
+             
  • 
+                 
    
+                     Use interval notation: e1-e20
+                 
    
+                 
    
+                     Which means all tracks from e1 up to e20, both
+                     included, and in the order found in the file.
+                 
    
+             
  • 
+                 
    
+                     You can of crouse combine the two notations: e3 e5 e10-e20
+                 
    
+         

+         

+              
+         

+         

+             With interval notation, the ordering is the one found in the file you
+             are processing, and is by no mean lexicographic (à la
+             dictionary). So in this example C1-C2 means C1, Cz, C2;
+             and T3-T4 means T3, C3, C1, Cz, C2, C4, T4:
+         

+         

+             
+         

+         

+             Exporting Computed Tracks
+         

+         

+             You can export the computed tracks by
+             using any of the following predefined names:
+         

+         
    
+             
  • 
+                 
    
+                     GFP  for the Global Field Power, if data are signed.
    
+             
  • 
+                 RMS for the Root Mean Square, instead of the
+                 GFP if data are positive.
    
+             
  • DIS  for the dissimilarity.
    
+             
  • AVG  for the average.
    
+         

+         

+             Exporting frequency files
+         

+         

+             See the Results paragraph.
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+     

  
 
\ No newline at end of file
diff --git a/docs/ReferenceGuide/ris-to-volumes.html b/docs/ReferenceGuide/ris-to-volumes.html
index 0989a1d1..208205c9 100644
--- a/docs/ReferenceGuide/ris-to-volumes.html
+++ b/docs/ReferenceGuide/ris-to-volumes.html
@@ -40,497 +40,711 @@
 
  
 
- 
-  

-   Results of Inverse Solutions to Volumes

-  

-    

-  

-   This toolbox will convert some 
-   .ris files, computed from 
-   this toolbox, into 
-   volumes. The aim is to be able to either 
-   display the results directly as volumes, 
-   or to fusion these results with other 3D modalities, like fMRI 
-   results.

-  

-    

-  

-   RIS to Volumes Dialog

-   Technical points & hints

-  

-   Grey mask

-  

-   Types of interpolation

-  

-   Output data types conversion

-  

-   Results

-  

-   RIS to Volumes Dialog

-  

-   Called from the  Tools
-    | Inverse Solutions | Results of Inverse Solutions to Volumes  menu, the following dialog 
-   appears:

-  

-    

-  

-   MRIs Preprocessing Dialog

-  

-    

-  

-    

-   
-       
-     
-     
-       
-       
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-	   
-     
-     
-       
-   

-      

-       Presets

-      

-       You can quickly set the most important parameters according to some 
-	   predefined scenarios. Then check and adjust the parameters to your 
-	   liking.

-      

-       (1) Volume Parameters

-      

-       Input and output volumes parameters.

-      

-       
-	   Grey Mask File:

-      

-       Give here the grey mask volume associated with the 
-	   Solution Points of of the inverse solution at hand.

-       You can Drag & Drop a
-	   volume file here.

-       This is the mask where the results will be actually computed.
-	   Don't give the full brain, or even worse, the full head, otherwise 
-	   you will have a lot of wrongful extrapolated values.

-       See this note for more details.

-      

-       Solution Points File:

-      

-       The Solution Points file, i.e. the positions in the 
-	   brain of the 
-   .ris files to be converted.

-       You can Drag & Drop a 
-	   
-   .spi file here.

-      

-       Interpolation Type:

-      

-       How to compute all the intermediate voxels from the grey 
-	   mask, given the sparse distribution of the solution points' 
-	   positions.

-       Pick one method from the list, sorted with increasing complexity and 
-	   visual quality.

-       See this note for more details.

-      

-       (2) Timely Parameters

-      

-        

-      

-       Processing All Data

-      

-       Does what it tells, every data point from the 
-   .ris file will be sequentially converted to a volume.

-       Be warry of the space it could take on your disk!

-      

-       Only Time Interval: 

-      

-       Specify only a time interval to be converted. A much 
-	   safer option than processing all data!

-      

-       From

-      

-       From which time frame (included)..

-      

-       To

-      

-       ..to which time frame (included)..

-      

-       by steps of:

-      

-       ..by time frame steps.

-       Data will be read by blocks of steps 
-	   size, then Median is applied for each 
-	   solution points.

-       Smaller steps will of course generated more data...

-      

-       (3) Output Options

-      

-        

-      

-       Optional Base File Name Prefix:

-      

-       You can give a meaningful file name prefix for all the resulting files, 
-	   or leave it empty.

-       Cartool will also postfix each file name with the current block of 
-	   TFs.

-      

-       Output Data Type:

-      

-       Currently, Cartool offers to save either the results as:
    
-		  
  • unsigned bytes: integer positive values ranging 
-		  in [0..255]
    • 
-		  
  • floating points: the real values from the input 
-   .ris files
    • 
-	  

-	  

-       Integer values use less space, are faster, and are good enough for display. 
-	   But this is not recommended for anything like statistics, as there will 
-	   be some loss during conversion.

-       Floating point values take more space, but are your real data. Use this option 
-	   if you want to proceed with some statistics f.ex.

-      

-       Output File Type:

-      

-       Pick from the list the file format (container) you want to save your 
-	   volumes to.

-      

-       Opening Results

-      

-       Does what is says. However, Cartool will prevent from opening too many 
-	   files.

-      

-       Process Current

-      

-       Enabled when called from a Tracks (RIS) window, the 
-       preprocessing will apply only to this file.

-      	 

-      

-       Batch Process

-      

-       Enabled when not called from a Tracks (RIS) 
-	   window:

-      
    
-       
  • 
-       
    
-        Clicking this button will open a dialog from which you can select a set
-         of RIS files, within a single directory.
    
-       
  • 
-       
    
-        Using Drag & Drop, you can drop files in the dialog and 
-        process them directly. Plus, it allows you to pick files from 
-        different directories, if you can select them through a handy 
-        utility like Everything beforehand.
    
-       

-      

-        

-		   

-      

-       Cancel

-      

-       Quit the dialog.

-      

-       Help

-      

-       Launch the Help to the right page (should be right here...).

-  

-   RIS to Volumes - Technical points & hints

-  

-   Grey mask

-  

-   The grey mask provided will constrain 
-   the outputs in some important ways.

-  

-   As a reminder, solution points are indeed a downsampled 
-   version of the grey mask given during the
-   computation of the inverse matrices. 
-   So you must use the same grey mask as the 
-   one used during the Inverse Matrix creation! Ris files, Solution 
-   Points and grey mask should match altogether to guarantee an optimal
-   interpolation.

-  

-    

-  

-   Here we can see how the grey mask and the solution points match (left), and 
-   and example of the interpolated results they can generate (right):

-  

-   

-  

-    

-  

-   If the mask provided is bigger than the original grey mask, 
-   then it will not be optimally covered by the solution points distribution. Voxels 
-   too far from any solution point will end up being extrapolated (instead of 
-   interpolated), "created from nothing" so to speak. 
-   This is definitely something to be avoided.

-  

-   Here we can see (left) that the brain has been used instead of the grey mask, 
-   or worse (right) the full head. A lot of internal voxels (white matter 
-   f.ex.), or external voxels (outside the brain) are literally created ex 
-   nihilo:

-  

-    

-  

-    

-  

-   In summary, use the correct grey mask associated to the inverse 
-   matrice's solution points. All other masks will generate some problems 
-   of their own (and who needs more problems?).

-  

-   Types of interpolation

-  

-   We can compute the value of any voxel that sits within a 
-   reasonable range of a set of solution points. To do that, we need an
-   interpolation formula that will combine the solution points' values, 
-   into a new value.

-  

-   Cartool provides 4 interpolation methods, all with pros and 
-   cons. There is no perfect method, any of them is basically creating 
-   values where there were none beforehand. This is not specific to Cartool, 
-   inverse solutions or EEG itself, just a general consideration.

-  

-    

-  

-   Here are the interpolations that have been deemed to be safe enough, so you 
-   can make up your mind (or use the default if you can't):

-  

-    

-  
-	  
-		  
-		  
-		  
-		  
-	  
-	  
-		  
-		  
-		  
-		  
-	  
-	  
-		  
-		  
-		  
-		  
-	  
-	  
-		  
-		  
-		  
-		  
-	  
-	  
-		  
-		  
-		  
-		  
-	  
-  
MethodWhat it doesProsCons
1 Nearest NeighborThe value from the 
-		  single closest solution point is takenNo new values are created, you see 
-	  only your data

No new maxima are created		No new values are created, so not really an 
-	  interpolation..

Results look like little cubes - visual aspect is therefor not very engaging (unless you are into
-	  cubism)
4 Nearest NeighborsThe values 
-		  from the 4 closest solution points are taken, and 
-		  mixed up according to the inverse of their relative distances
-		  
-	  	A 
-	  well-know interpolation

This is the interpolation used for
-	  display of inverse solutions


-		  No new maxima 
-	  are created		Results look a bit jagged or serrated
LinearThe values from the
-		  8 solution points around a given voxel are taken, and 
-		  linearly mixed
-		  A well-known interpolation


-		  No new maxima are created		Results are smooth, but still look a little bit 
-	  like patches or blocks
Cubic SplineThe values from a box of 
-		  5x5x5 (125) solution points around a given voxel are taken, and mixed up 
-   according to a cubic B-spline kernelBest looking results
-		  so smooth, any 
-	  reviewer resisting its sex-appeal is desperately cold-hearted


-		  No new 
-	  maxima are created with the Cartool implementation only		Your colleagues will be jealous, deal with 
-	  it

-  

-    

-  

-    

-  

-   See here a side by side visual comparison of the 4 interpolations, 1NN (top 
-   left), 4NN (top right), Linear (bottom left) and 
-   Cubic Spline (bottom right):

-  

-   

-   

-  

-    

-  

-    

-  

-   No new maxima policy

-  

-   To conclude, the Cartool implementation of these interpolation methods has 
-   been done in such a way to ensure that no new 
-   maxima are being artificially created.

-  

-   This is an important point, as f.ex. a regular Cubic B-Spline 
-   interpolation can generated new maxima, and even negative values 
-   even from a positive input. This is to be totally avoided, as the 
-   maximum position can be of utmost importance, and artificially displacing it 
-   is not an option. 

-  

-   Output data type conversion

-  

-   Cartool can currently output 2 types of data:

-  
    
-		  
  • unsigned bytes: integer positive values, in the range [0..255]
    • 
-		  
  • floating points: the real values from the input 
-   .ris files
    • 
-	  

-	  

-        

-       When saving into integer, data will be rescaled by an optimal 
-	   power-of-10 factor, so that the rescaled value will fit into [0..255]. 
-	   F.ex. data in a range of 0.0006 to 0.0230 will be multiplied by 10'000 so 
-	   to finally fit in the range 6 to 230.

-   Whereas no scaling is needed when saving as floating points. 
-   The exact values are written to file.

-  

-   If you aim at doing statistics, or proceed with some more processing of your 
-   own, then save as floating points at the cost of bigger files. If you just 
-   aim for visualization, then you may use the unsigned byte version, which 
-   produces smaller files.

-  

-   RIS to Volumes - Results

-  
    
-   
  • 
-   
    
-    Preprocessed files are written in the same directories as their sources.
-     
    Output file names can have the user's prefix 
-	added, and a postfix composed from the current 
-	block of time frames.
    To remember that we are dealing with 
-	volumes from .ris, the .ris 
-	string is added before the file extension, too:
    
-   
      
-	   
    • 
-	   
      <input file>.<infix>.TFXXX-YYY.ris.hdr
      or
      
-	   
    • 
-	   
       <prefix>.<input file>.TFXXX-YYY.ris.hdr
      
-   
    
-   
  • 
-   
    
-    Verbose file .vrb 
-    (text), showing all the parameters.
    
-   

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-    

-    
+ 
+     

+         

+             Results of Inverse Solutions to Volumes
+         

+         

+              
+         

+         

+             This toolbox will convert some 
+                 
+                     
+                         .ris
+                     
+                 
+              files, computed from 
+                 this toolbox
+             , into 
+                 volumes
+             . The aim is to be able to either 
+                 display the results directly as volumes
+             ,
+             or to fusion these results with other 3D modalities, like fMRI
+             results.
+         

+         

+              
+         

+         

+             RIS to Volumes Dialog

+             Technical points & hints
+         

+         

+             Grey mask
+         

+         

+             Types of interpolation
+         

+         

+             Output data types conversion
+         

+         

+             Results
+         

+         

+             RIS to Volumes Dialog
+         

+         

+             Called from the  
+                 
+                     Tools
+                     | Inverse Solutions | Results of Inverse Solutions to Volumes
+                 
+               menu, the following dialog
+             appears:
+         

+         

+              
+         

+         

+             MRIs Preprocessing Dialog
+         

+         

+              
+         

+         

+              
+         

+         
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+             
+                 
+                 
+             
+         

+                     

+                         Presets
+                 

+                     

+                         You can quickly set the most important parameters according to some
+                         predefined scenarios. Then check and adjust the parameters to your
+                         liking.
+                 

+                     

+                         (1) Volume Parameters
+                 

+                     

+                         Input and output volumes parameters.
+                 

+                     

+                         
+                         Grey Mask File:
+                 

+                     

+                         Give here the grey mask volume associated with the
+                         Solution Points of of the inverse solution at hand.
+                     

+                         You can Drag & Drop a
+                         volume file here.
+                     

+                         This is the mask where the results will be actually computed.
+                         Don't give the full brain, or even worse, the full head, otherwise
+                         you will have a lot of wrongful extrapolated values.
+                     

+                         See this note for more details.
+                 

+                     

+                         Solution Points File:
+                 

+                     

+                         The Solution Points file, i.e. the positions in the
+                         brain of the 
+                             
+                                 
+                                     .ris
+                                 
+                             
+                          files to be converted.
+                     

+                         You can Drag & Drop a 
+                             
+                                 
+                                     .spi
+                                 
+                             
+                          file here.
+                 

+                     

+                         Interpolation Type:
+                 

+                     

+                         How to 
+                             compute all the intermediate voxels from the grey
+                             mask
+                         , given the sparse distribution of the solution points'
+                         positions.
+                     

+                         Pick one method from the list, sorted with increasing complexity and
+                         visual quality.
+                     

+                         See this note for more details.
+                 

+                     

+                         (2) Timely Parameters
+                 

+                     

+                          
+                 

+                     

+                         Processing All Data
+                 

+                     

+                         Does what it tells, every data point from the 
+                             
+                                 
+                                     .ris
+                                 
+                             
+                          file will be sequentially converted to a volume.
+                     

+                         Be warry of the space it could take on your disk!
+                 

+                     

+                         Only Time Interval: 
+                 

+                     

+                         Specify only a time interval to be converted. A much
+                         safer option than processing all data!
+                 

+                     

+                         From
+                 

+                     

+                         From which time frame (included)..
+                 

+                     

+                         To
+                 

+                     

+                         ..to which time frame (included)..
+                 

+                     

+                         by steps of:
+                 

+                     

+                         ..by time frame steps.
+                     

+                         Data will be read by blocks of steps
+                             size
+                         , then Median is applied for each
+                         solution points.
+                     

+                         Smaller steps will of course generated more data...
+                 

+                     

+                         (3) Output Options
+                 

+                     

+                          
+                 

+                     

+                         Optional Base File Name Prefix:
+                 

+                     

+                         You can give a meaningful file name prefix for all the resulting files,
+                         or leave it empty.
+                     

+                         Cartool will also postfix each file name with the current block of
+                         TFs.
+                 

+                     

+                         Output Data Type:
+                 

+                     

+                         Currently, Cartool offers to save either the results as:
    
+                             
  • 
+                                 unsigned bytes: integer positive values ranging
+                                 in [0..255]
+                             
    • 
+                             
  • 
+                                 floating points: the real values from the input 
+                                     
+                                         
+                                             .ris
+                                         
+                                     
+                                  files
+                             
    • 
+                         

+                     

+                         Integer values use less space, are faster, and are good enough for display.
+                         But this is not recommended for anything like statistics, as there will
+                         be some loss during conversion.
+                     

+                         Floating point values take more space, but are your real data. Use this option
+                         if you want to proceed with some statistics f.ex.
+                 

+                     

+                         Output File Type:
+                 

+                     

+                         Pick from the list the file format (container) you want to save your
+                         volumes to.
+                 

+                     

+                         Opening Results
+                 

+                     

+                         Does what is says. However, Cartool will prevent from opening too many
+                         files.
+                 

+                     

+                         Process Current
+                 

+                     

+                         Enabled when called from a Tracks (RIS) window, the
+                         preprocessing will apply only to this file.
+                     

+                 

+                     

+                         Batch Process
+                 

+                     

+                         Enabled when not called from a 
+                             Tracks (RIS)
+                             window
+                         :
+                     

+                     
    
+                         
  • 
+                             
    
+                                 Clicking this button will open a dialog from which you can select a 
+                                     set
+                                     of RIS files
+                                 , within a single directory.
+                             
    
+                         
  • 
+                             
    
+                                 Using Drag & Drop, you can drop files in the dialog and
+                                 process them directly. Plus, it allows you to pick files 
+                                     from
+                                     different directories
+                                 , if you can select them through a handy
+                                 utility like Everything beforehand.
+                             
    
+                     

+                     

+                          
+                     

+                 

+                     

+                         Cancel
+                 

+                     

+                         Quit the dialog.
+                 

+                     

+                         Help
+                 

+                     

+                         Launch the Help to the right page (should be right here...).
+                 

+         

+             RIS to Volumes - Technical points & hints
+         

+         

+             Grey mask
+         

+         

+             The grey mask provided will constrain
+             the outputs in some important ways.
+         

+         

+             As a reminder, solution points are indeed a 
+                 downsampled
+                 version of the grey mask
+              given during the
+             computation of the inverse matrices.
+             So you must 
+                 use the same grey mask as the
+                 one used during the Inverse Matrix creation!
+              Ris files, Solution
+             Points and grey mask should match altogether to guarantee an optimal
+             interpolation.
+         

+         

+              
+         

+         

+             Here we can see how the grey mask and the solution points match (left), and
+             and example of the interpolated results they can generate (right):
+         

+         

+             
+         

+         

+              
+         

+         

+             If the mask provided is bigger than the original grey mask,
+             then it will not be optimally covered by the solution points distribution. Voxels
+             too far from any solution point will end up being extrapolated (instead of
+             interpolated), "created from nothing" so to speak. 
+                 This is definitely something to be avoided.
+             
+         

+         

+             Here we can see (left) that the brain has been used instead of the grey mask,
+             or worse (right) the full head. A lot of internal voxels (white matter
+             f.ex.), or external voxels (outside the brain) are literally created 
+                 ex
+                 nihilo
+             :
+         

+         

+              
+         

+         

+              
+         

+         

+             In summary, use the correct 
+                 grey mask associated to the inverse
+                 matrice's solution points
+             . All other masks will generate some problems
+             of their own (and who needs more problems?).
+         

+         

+             Types of interpolation
+         

+         

+             We can compute the value of any voxel that sits within a 
+                 reasonable range of a set of solution points
+             . To do that, we need an
+             interpolation formula that will combine the solution points' values,
+             into a new value.
+         

+         

+             Cartool provides 4 interpolation methods, all with pros and
+             cons. There is no perfect method, any of them is basically creating
+             values where there were none beforehand. This is not specific to Cartool,
+             inverse solutions or EEG itself, just a general consideration.
+         

+         

+              
+         

+         

+             Here are the interpolations that have been deemed to be safe enough, so you
+             can make up your mind (or use the default if you can't):
+         

+         

+              
+         

+         
+             
+                 
+                 
+                 
+                 
+             
+             
+                 
+                 
+                 
+                 
+             
+             
+                 
+                 
+                 
+                 
+             
+             
+                 
+                 
+                 
+                 
+             
+             
+                 
+                 
+                 
+                 
+             
+         
MethodWhat it doesProsCons
1 Nearest Neighbor
+                     The value from the 
+                         single closest solution point
+                      is taken
+                 
+                     No new values are created, you see
+                     only your data

No new maxima are created
+                 		
+                     No new values are created, so not really an
+                     interpolation..

Results look like little cubes - visual aspect is therefor not very engaging (unless you are into
+                     cubism)
+                 
4 Nearest Neighbors
+                     The values
+                     from the 4 closest solution points are taken, and
+                     mixed up according to the inverse of their relative distances
+                 
+                     
+                         A
+                         well-know interpolation
+                     

This is the interpolation used for
+                     display of inverse solutions


+                     
+                         No new maxima
+                         are created
+                     
+                 		Results look a bit jagged or serrated
Linear
+                     The values from the
+                     8 solution points around a given voxel are taken, and
+                     linearly mixed
+                 
+                     A well-known interpolation


+                     No new maxima are created
+                 		
+                     Results are smooth, but still look a little bit
+                     like patches or blocks
+                 
Cubic Spline
+                     The values from a box of
+                     5x5x5 (125) solution points around a given voxel are taken, and mixed up
+                     according to a cubic B-spline kernel
+                 
+                     Best looking results
+                     
+                         so smooth, any
+                         reviewer resisting its sex-appeal is desperately cold-hearted
+                     


+                     
+                         No new
+                         maxima are created with the Cartool implementation only
+                     
+                 		
+                     Your colleagues will be jealous, deal with
+                     it
+                 

+         

+              
+         

+         

+              
+         

+         

+             See here a side by side visual comparison of the 4 interpolations, 1NN (top
+             left), 4NN (top right), Linear (bottom left) and
+             Cubic Spline (bottom right):
+         

+         

+             

+             
+         

+         

+              
+         

+         

+              
+         

+         

+             No new maxima policy
+         

+         

+             To conclude, the Cartool implementation of these interpolation methods has
+             been done in such a way to ensure that 
+                 no new
+                 maxima are being artificially created.
+             
+         

+         

+             This is an important point, as f.ex. a 
+                 regular Cubic B-Spline
+                 interpolation can generated new maxima, and even negative values
+             
+             even from a positive input. This is to be totally avoided, as the
+             maximum position can be of utmost importance, and artificially displacing it
+             is not an option. 
+         

+         

+             Output data type conversion
+         

+         

+             Cartool can currently output 2 types of data:
+         

+         
    
+             
  • unsigned bytes: integer positive values, in the range [0..255]
    • 
+             
  • 
+                 floating points: the real values from the input 
+                     
+                         
+                             .ris
+                         
+                     
+                  files
+             
    • 
+         

+         

+              
+         

+             When saving into integer, 
+                 data will be rescaled by an optimal
+                 power-of-10 factor
+             , so that the rescaled value will fit into [0..255].
+             F.ex. data in a range of 0.0006 to 0.0230 will be multiplied by 10'000 so
+             to finally fit in the range 6 to 230.
+         

+             Whereas no scaling is needed when saving as floating points.
+             The exact values are written to file.
+         

+         

+             If you aim at doing statistics, or proceed with some more processing of your
+             own, then save as floating points at the cost of bigger files. If you just
+             aim for visualization, then you may use the unsigned byte version, which
+             produces smaller files.
+         

+         

+             RIS to Volumes - Results
+         

+         
    
+             
  • 
+                 
    
+                     Preprocessed files are written in the same directories as their sources.
+                     
    Output file names can have the user's prefix
+                     added, and a postfix composed from the current 
+                         block of time frames
+                     .
    To remember that we are dealing with
+                     volumes from .ris, the .ris
+                     string is added before the file extension, too:
+                 
    
+                 
      
+                     
    • 
+                         
      <input file>.<infix>.TFXXX-YYY.ris.hdr
      or
      
+                     
    • 
+                         
       <prefix>.<input file>.TFXXX-YYY.ris.hdr
      
+                 
    
+             
  • 
+                 
    
+                     Verbose file .vrb
+                     (text), showing all the parameters.
+                 
    
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+              
+         

+              
+     

  
 
\ No newline at end of file
diff --git a/docs/ReferenceGuide/terms-definitions-formulas.html b/docs/ReferenceGuide/terms-definitions-formulas.html
index 36c9e68a..f53e53df 100644
--- a/docs/ReferenceGuide/terms-definitions-formulas.html
+++ b/docs/ReferenceGuide/terms-definitions-formulas.html
@@ -8,489 +8,642 @@
 }
 
  
- 
-  

-   Appendix B

-   Cartool Slang & Various Formulas

-  

-    

-  

-   Formulas
Data types

-   String regular expression

-   Segmentation
Tracks

-   Triggers, Markers & Events
Cursor

-   MRIs and volumes
Documents & views

-   OpenGL Graphic

-  

-   Formulas

-  

-   Let's define:

-  

-   n = number of electrodes,

-   Uorg i = measured voltage of electrode i,
-    against the recording reference,

-   

-   

-   

-  

-   The Average Reference:

-    

-  

-   The valued vi and ui used in the following 
-   formulas are (subtracting the average reference): and

-   

-   

-   

-   

-  

-   The Global Field Power (GFP) is the standard 
-   deviation of the data:

-   

-   

-   

-   

-   

-  

-   The Dissimilarity is the square 
-   root of the mean of the squared differences between the potentials 
-   measured at all corresponding electrodes. Since only landscape 
-   differences are of interest, the maps are first scaled to unitary 
-   strength by dividing the voltage at each electrode by the GFP: withand

-  

-   The Dissimilarity ranges from 0 to 2. Diss=2 means that the two maps 
-   are inverted, Diss=0 means that they are similar.

-   Dissimilarity and Global Field Power have been developed by Lehmann 
-   & Skrandies, 1980.

-   

-   

-   

-   

-  

-   The Spatial Correlation between two 
-   maps is mathematically defined as:

-   

-   The relation between Dissimilarity and correlation has been developed 
-   by Brandeis et al., 1992. He showed that:

-   or

-   Correlation ranges from -1 to +1. C = -1 means that the two maps are 
-   inverted, C = +1 means that they are similar.

-   

-   

-   

-   

-   The Explained Variance (EV) gives the amount of variance over 
-   all electrodes of a given map that is explained by another map. It is 
-   calculated as:

-   

-   Therefor, the relation between correlation and explained variance is 
-   the same as between the two statistical values variance and standard deviation:

-   or

-   

-   

-   

-   

-  

-   The Global Explained Variance (GEV) is NOT 
-   just the mean of the explained variances over a time period and is 
-   NOT the mean correlation of the segment map in the time period. The 
-   global explained variance is the sum of the explained variances 
-   WEIGHTED by the Global Field Power at each moment in time:

-   

-   Thus, a map that explains a short period with high GFP might have a 
-   higher GEV than a map that explains a long time period with low GFP.

-  

-   It is worth mentioning that the summation of all time frames can also 
-   be split into contributions for each segment (in which the segment 
-   map is constant). Then, for q segments/clusters:

-   

-   

-   

-   

-   

-  

-   The Cross Validation  (CV) 
-   for a number q of clusters is a modified version of the 
-   predictive residual variance:

-   

-   with  
-   as the normalized vector chosen by the segmentation at time point t,
-    v as the vector of voltages vi, the 
-   estimator of the noise variance being (or put simply, the error done 
-   by the segmentation):

-   

-  

-   The value of q minimizing the cross validation is the optimal 
-   number of clusters/maps.

-  

-   Data types in Cartool

-  

-   Data handled in Cartool can be:

-  
    
-   
  • 
-   
    
-    Scalar, positive-only values (also referred as "Positive Data")
    
-   
  • 
-   
    
-    Scalar, signed values
    
-   
      
-    
    • 
-    
      
-     with Average Reference
      
-     
    • without Average Reference
      
-    
    
-   
  • 
-   
    
-    Vectorial values
    
-   

-  

-    

-  

-   Positive-only values could be f.ex. the norms of the Results
-    of Inverse Solution, or spikes counting of some 
-   sorts, etc... where negative values are irrelevant.

-  

-   Scalar, signed values are the usual EEG data. That is, 
-   values can be whatever, positive or negative. We can further 
-   distinguish EEG data with or without Average Reference. Surface 
-   recordings (on the scalp) are always analysed with Average
-    Reference (we don't really promote reference against a 
-   single or a set of electrodes BTW), while depth electrodes recordings 
-   are done without Average Reference.

-  

-   Vectorial values are usually the Results of the Inverse Solutions,
-    which produce 3D vectors at each solution point location. Cartool 
-   can optionally show you 
-   these vectors, but most of the time, what you see are only the 
-   norms of these vectors, as with the EEG 
-   tracks display or with all 
-   these sorts of 3D blobs. Nonetheless, the data behind are 
-   of vectorial nature.

-  

-   Know which data you're working on!

-  

-   Because Cartool can be parameterized for all those cases, and the 
-   results will be different if you make the wrong choices, you have 
-   to carefully select all the settings about data-type!

-  

-   Fortunately for you, many of the processings 
-   now have a Presets drop-down menu (see here
-    f.ex.) for you to pick the right data type setting (or a very 
-   close one you can fine-tune).

-  

-   On the influence on formulas

-  

-   Data labeled as Positive-only values will be applied slightly 
-   different formulas. Mainly, all formulas 
-   which first step is an average reference will simply skip it. No 
-   average reference will be applied, because it has no meaning in these cases.

-  

-   GFP (Global Field Power) will become a RMS (Root 
-   Mean Square), and the other formulas keep their names, like the Correlation,
-    Dissimilarity, GEV 
-   (Global Explained Variance), etc...

-  

-   String regular expressions

-  

-   In a nutshell, regular
-    expressions are a powerful way to find matches across 
-   a list of strings. It uses a special
-    syntax that you can learn bit by bit, according to your needs, 
-   which can help you launch very powerful requests.

-  

-    

-  

-   This is no tutorial on the subject, but just to show you a few common 
-   examples. Suppose your files have the following trigger / marker names:

-  
    
-   
    
-    EyesOpen, EyesClosed,
    
-   
    
-    Trigger1, Trigger2, Trigger10, Trigger20,
    
-   
    
-    GfpAbove80, GfpAbove90, GfpAbove100
    
-   

-  

-    

-  

-   And we want to Search
-    for marker, let see some basic requests and their answers.

-  

-    

-  

-   First, the most intuitive search is to simply give a string of characters,
-    which will then return any marker name that contains these characters:

-  
    
-   
  • 
-   
    
-    "Eyes" –> EyesOpen, EyesClosed
    
-   
  • 
-   
    
-    "Trig" –> Trigger1, Trigger2, Trigger10, Trigger20
    
-   
  • 
-   
    
-    "1" –> Trigger1, Trigger10, GfpAbove100
    
-   
  • 
-   
    
-    "0" –> Trigger10, Trigger20, GfpAbove80, 
-    GfpAbove90, GfpAbove100
    
-   

-  

-    

-  

-   Then we can introduce the special meaning character ".",
-    which means "can be any character except a space":

-  
    
-   
  • 
-   
    
-    "1." (a 1 followed by any character) –> Trigger10, GfpAbove100
    
-   
  • 
-   
    
-    "T......1" (a T followed by any 6 characters then a 1) 
-    –> Trigger1, Trigger10
    
-   

-  

-    

-  

-   Other useful special characters are "(", "|"
-    and ")" to set a list of possible alternatives:

-  
    
-   
  • 
-   
    
-    "Eyes(Open|Closed)" (Eyes then either Open or Closed) 
-    –> EyesOpen, EyesClosed
    
-   
  • 
-   
    
-    "Trigger(1|20)" –> Trigger1, Trigger20
    
-   
  • 
-   
    
-    "Above(90|100)" –> GfpAbove90, GfpAbove100
    
-   

-  

-   Segmentation

-  

-   Map: the 2D / 3D visual representation of the 
-   EEG potentials at a given time point:

-  

-    

-  

-   But a map is actually only a...

-  

-   Vector of values (e1, e2,
-    e3, ..., en), for n electrodes.

-  

-   Segment: a set of maps which have been 
-   said to belong to the same group. To identify the segments, we use a...

-  

-   Labeling: simply a numbering for each time 
-   point, telling to which segment it has been assigned. F.ex. 
-   1,1,1,2,2,3,3,3,3... first segment: the 3 first time points, second segment: 
-   time points 4 & 5... Graphically rendered, with time as horizontal axis, and 
-   one color per segment:

-  

-    

-  

-   Cluster: another name for a segment, but 
-   seen from the clustering algorithm point of view. A set of vectors 
-   that have been grouped together.

-  

-   Templates (landscape maps): the set of n 
-   synthetic maps produced by the segmentation that will best represent 
-   the data. Also called centroids, they are usually computed as the average of 
-   a set of maps. See here f.ex. the 4 template maps given by 4 segments:

-  

-   

-  

-   See also the Segmentation & Fitting page.

-  

-   Tracks

-  

-   Tracks: (or channels, or regular tracks) The display 
-   representation of the electrodes' recordings in time.

-  

-   Auxiliary tracks: The tracks of the auxiliary electrodes (like 
-   ECG, EOG...), plotted in light blue.

-  

-   Bad tracks: Tracks (usually regular tracks, but auxiliaries 
-   are also possible) that have been set as bad by the user. F.ex. 
-   noisy, meaningless tracks. The bad tracks are excluded from the 
-   computed tracks process, and are plotted in light transparent red.

-  

-   Computed tracks: These are not recorded tracks, but are 
-   computed on-line by Cartool, and will appear separately at the bottom 
-   of the Eeg display in blue. Presently computed tracks are: GFP,
-    Dissimilarity and Average.
-    Any change on the data, like filtering or setting some tracks as bad 
-   will affect the computation, which can be seen in real-time.

-  

-   From top to down, the regular tracks, some auxiliary tracks, then two 
-   computed tracks:

-  

-   

-    

-   

-  

-   Triggers, Markers & Events

-  

-   Trigger: a trigger is a flag already contained in 
-   the original Eeg file, usually sent by the stimulation machine 
-   when a given event occured (stimuli presentation f.ex.). The 
-   user can hide the triggers, but can not delete nor modify them. F.ex. 
-   here triggers 1 and 2 were sent when reversing a checkerboard on the screen:

-   

-  

-   Events: in some cases, the recorded file 
-   can also contain events sent by the stimulation machine, but which 
-   are not triggers by themselves (ie not synchronized to the stimuli 
-   presentation). For example initialization events, subject responses 
-   from the keypad, reaction times, etc... They too can not be deleted.

-  

-   Marker: a marker is a user defined 
-   flag manually set in the Eeg, with any description attached to it. 
-   The user can add and delete them as needed, and even generate them 
-   through computation (see Markers menu 
-   ). They are written in an external file (see .mrk 
-   file format). F.ex. here two markers were added:

-   

-  

-   Epoch: a small time interval of an 
-   EEG. It consists in an origin and two intervals, one before 
-   and one after its origin. The origin is usually a trigger from 
-   an experiment, and the whole duration will give the size if the ERP computed.

-  

-   There is rarely a single epoch to be considered, but rather a whole 
-   serie of them.

-  

-   ERP: Evoked Response Potentials (in case you 
-   don't know).

-  

-   Cursor

-  

-   Cursor: the current position in the Eeg, shown in red. Usually 
-   it is a single time frame in the Eeg:

-   

-  

-   Extended cursor: the cursor can extend to many time frames. 
-   This period of time can be used for averages, or time sequences for 
-   the display:

-   

-  

-   Frequency cursor: a cursor to select some frequency range, 
-   show in blue. This applies only to frequency files:

-   

-  

-   Time frame: (or time point) while 
-   recording the Eeg, each sample is numbered, starting from 0 to N-1, N 
-   being the total number of samples. It is therefor an index in the 
-   acquisition sequence, but not the time (in 
-   milliseconds/seconds/minutes) itself.

-  

-   Sampling frequency: the number of samples per second of the 
-   Eeg values. This value makes possible to translate from time frames 
-   to milliseconds, which is more understanble and mandatory for some 
-   processings (filters f.ex.).

-  

-   MRIs and volumes

-  

-   Isosurface: a mathematical surface 
-   which cuts through a volume at a constant value. An isosurface 
-   is simply defined by this constant value, telling at which "grey 
-   level" the volume is to be cut.

-   Simply put, it is like a hollow veil molded around a volume (the data 
-   at a given value).

-   The now classical Marching Cube algorithm is used, with collapsed 
-   triangles decimation only. Also, the data are Gaussian filtered 
-   before the process, to remove small artifacts, to give a smoother 
-   surface and less triangles.

-  

-   Voxel: a volume element (derived from 
-   pixel, picture element, that's for the 'x'), the smallest part that 
-   can be accessed in a full volume. Voxels are usually indexed by 3 
-   coordinates, as they are in 3 dimensions, but these indexes may not 
-   have the meaning of X, Y and Z, or whatever you expect them to be...

-  

-   Documents and Views

-  

-   Documents: the actual data read from file are put in a 
-   Document. Documents are only numbers in memory, you can't see them. 
-   For this purpose, views are attached to them.

-  

-   Views: to see the data, you need at least 
-   one view, but you can add as many views as you want, all reflecting 
-   the current data from its Document. Views can 
-   be of different types, to allow various explorations or analysis. 
-   These types are most of the time context sensitive.

-  

-   F.ex. a document with Eeg contents (= simply a matrix of numbers), 
-   with 3 views attached at the same time, one view with all 2D Eeg 
-   tracks superimposed, one view with 3D Eeg tracks, one view with a 2D 
-   interpolated color rendering 
-   of a given time frame:

-  

-   

-    Document

-    ____

-    |

-   

-  

-   

-            
-	Views

-   

-  

-   OpenGL Graphic

-  

-    ®

-  

-   OpenGL is a standard and very powerful graphic library for 3D 
-   rendering, first developped by Silicon Graphics, then transferred to 
-   other platforms. OpenGL is evolving, so it has a version number 
-   associated with it. Cartool right now is compatible with version 1.1 
-   and higher.

-  

-   It is nearly mandatory to have a graphic cards that will accelerate 
-   OpenGL operations to have decent performance. Though you can 
-   theoretically work without... but I warned you.

-  

-   See www.opengl.org for more informations.

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    
+ 
+     

+         

+             Appendix B

+             Cartool Slang & Various Formulas
+         

+         

+              
+         

+         

+             Formulas
Data types

+             String regular expression

+             Segmentation
Tracks

+             Triggers, Markers & Events
Cursor

+             MRIs and volumes
Documents & views

+             OpenGL Graphic
+         

+         

+             Formulas
+         

+         

+             Let's define:
+         

+         

+             n = number of electrodes,

+             Uorg i = measured voltage of electrode i,
+             against the recording reference,

+             

+             

+         

+         

+             The Average Reference:

+              
+         

+         

+             The valued vi and ui used in the following
+             formulas are (subtracting the average reference): and

+             

+             

+             

+         

+         

+             The Global Field Power (GFP) is the standard
+             deviation of the data:

+             

+             

+             

+             

+         

+         

+             The Dissimilarity is the square
+             root of the mean of the squared differences between the potentials
+             measured at all corresponding electrodes. Since only landscape
+             differences are of interest, the maps are first scaled to unitary
+             strength by dividing the voltage at each electrode by the GFP: withand
+         

+         

+             The Dissimilarity ranges from 0 to 2. Diss=2 means that the two maps
+             are inverted, Diss=0 means that they are similar.

+             Dissimilarity and Global Field Power have been developed by Lehmann
+             & Skrandies, 1980.

+             

+             

+             

+         

+         

+             The Spatial Correlation between two
+             maps is mathematically defined as:

+             

+             The relation between Dissimilarity and correlation has been developed
+             by Brandeis et al., 1992. He showed that:

+             or

+             Correlation ranges from -1 to +1. C = -1 means that the two maps are
+             inverted, C = +1 means that they are similar.

+             

+             

+             

+             

+             The Explained Variance (EV) gives the amount of variance over
+             all electrodes of a given map that is explained by another map. It is
+             calculated as:

+             

+             Therefor, the relation between correlation and explained variance is
+             the same as between the two statistical values variance and standard deviation:

+             or

+             

+             

+             

+         

+         

+             The Global Explained Variance (GEV) is NOT
+             just the mean of the explained variances over a time period and is
+             NOT the mean correlation of the segment map in the time period. The
+             global explained variance is the sum of the explained variances
+             WEIGHTED by the Global Field Power at each moment in time:

+             

+             Thus, a map that explains a short period with high GFP might have a
+             higher GEV than a map that explains a long time period with low GFP.
+         

+         

+             It is worth mentioning that the summation of all time frames can also
+             be split into contributions for each segment (in which the segment
+             map is constant). Then, for q segments/clusters:

+             

+             

+             

+             

+         

+         

+             The Cross Validation  (CV)
+             for a number q of clusters is a modified version of the
+             predictive residual variance:

+             

+             with 
+             as the normalized vector chosen by the segmentation at time point t,
+             v as the vector of voltages vi, the
+             estimator of the noise variance being (or put simply, the error done
+             by the segmentation):

+             
+         

+         

+             The value of q minimizing the cross validation is the optimal
+             number of clusters/maps.
+         

+         

+             Data types in Cartool
+         

+         

+             Data handled in Cartool can be:
+         

+         
    
+             
  • 
+                 
    
+                     Scalar, positive-only values (also referred as "Positive Data")
+                 
    
+             
  • 
+                 
    
+                     Scalar, signed values
+                 
    
+                 
      
+                     
    • 
+                         
      
+                             with Average Reference
      
+                     
    • without Average Reference
      
+                 
    
+             
  • 
+                 
    
+                     Vectorial values
+                 
    
+         

+         

+              
+         

+         

+             Positive-only values could be f.ex. the 
+                 norms of the 
+                     Results
+                     of Inverse Solution
+                 
+             , or spikes counting of some
+             sorts, etc... where negative values are irrelevant.
+         

+         

+             Scalar, signed values are the usual EEG data. That is,
+             values can be whatever, positive or negative. We can further
+             distinguish EEG data with or without Average Reference. Surface
+             recordings (on the scalp) are always analysed 
+                 with 
+                     Average
+                     Reference
+                 
+              (we don't really promote reference against a
+             single or a set of electrodes BTW), while depth electrodes recordings
+             are done without Average Reference.
+         

+         

+             Vectorial values are usually the Results of the Inverse Solutions,
+             which produce 3D vectors at each solution point location. Cartool
+             can optionally 
+                 show you
+                 these vectors
+             , but most of the time, what you see are only the
+             norms of these vectors, 
+                 as with the EEG
+                 tracks display
+              or 
+                 with all
+                 these sorts of 3D blobs
+             . Nonetheless, the data behind are
+             of vectorial nature.
+         

+         

+             Know which data you're working on!
+         

+         

+             Because Cartool can be parameterized for all those cases, and the
+             results will be different if you make the wrong choices, 
+                 you have
+                 to carefully select all the settings about data-type!
+             
+         

+         

+             Fortunately for you, many of the processings
+             now have a Presets drop-down menu (see 
+                 here
+                 f.ex.
+             ) for you to pick the right data type setting (or a very
+             close one you can fine-tune).
+         

+         

+             On the influence on formulas
+         

+         

+             Data labeled as Positive-only values will be applied slightly
+             different formulas. Mainly, 
+                 all formulas
+                 which first step is an average reference will simply skip it
+             . No
+             average reference will be applied, because it has no meaning in these cases.
+         

+         

+             GFP (Global Field Power) will become a RMS (Root
+             Mean Square), and the other formulas keep their names, like the Correlation,
+             Dissimilarity, GEV
+             (Global Explained Variance), etc...
+         

+         

+             String regular expressions
+         

+         

+             In a nutshell, 
+                 
+                     
+                         regular
+                         expressions
+                     
+                 
+              are a powerful way to 
+                 find matches across
+                 a list of strings
+             . It uses a 
+                 special
+                 syntax
+              that you can learn bit by bit, according to your needs,
+             which can help you launch very powerful requests.
+         

+         

+              
+         

+         

+             This is no tutorial on the subject, but just to show you a few common
+             examples. Suppose your files have the following trigger / marker names:
+         

+         
    
+             
    
+                 EyesOpen, EyesClosed,
+             
    
+             
    
+                 Trigger1, Trigger2, Trigger10, Trigger20,
+             
    
+             
    
+                 GfpAbove80, GfpAbove90, GfpAbove100
+             
    
+         

+         

+              
+         

+         

+             And we want to 
+                 
+                     Search
+                     for marker
+                 
+             , let see some basic requests and their answers.
+         

+         

+              
+         

+         

+             First, the most intuitive search is to simply give a string of characters,
+             which will then return any marker name that contains these characters:
+         

+         
    
+             
  • 
+                 
    
+                     "Eyes" –> EyesOpen, EyesClosed
+                 
    
+             
  • 
+                 
    
+                     "Trig" –> Trigger1, Trigger2, Trigger10, Trigger20
+                 
    
+             
  • 
+                 
    
+                     "1" –> Trigger1, Trigger10, GfpAbove100
+                 
    
+             
  • 
+                 
    
+                     "0" –> Trigger10, Trigger20, GfpAbove80,
+                     GfpAbove90, GfpAbove100
+                 
    
+         

+         

+              
+         

+         

+             Then we can introduce the special meaning character ".",
+             which means "can be any character except a space":
+         

+         
    
+             
  • 
+                 
    
+                     "1." (a 1 followed by any character) –> Trigger10, GfpAbove100
+                 
    
+             
  • 
+                 
    
+                     "T......1" (a T followed by any 6 characters then a 1)
+                     –> Trigger1, Trigger10
+                 
    
+         

+         

+              
+         

+         

+             Other useful special characters are "(", "|"
+             and ")" to set a list of possible alternatives:
+         

+         
    
+             
  • 
+                 
    
+                     "Eyes(Open|Closed)" (Eyes then either Open or Closed)
+                     –> EyesOpen, EyesClosed
+                 
    
+             
  • 
+                 
    
+                     "Trigger(1|20)" –> Trigger1, Trigger20
+                 
    
+             
  • 
+                 
    
+                     "Above(90|100)" –> GfpAbove90, GfpAbove100
+                 
    
+         

+         

+             Segmentation
+         

+         

+             Map: the 2D / 3D visual representation of the
+             EEG potentials at a given time point:
+         

+         

+              
+         

+         

+             But a map is actually only a...
+         

+         

+             Vector of values (e1, e2,
+             e3, ..., en), for n electrodes.
+         

+         

+             Segment: a set of maps which have been
+             said to belong to the same group. To identify the segments, we use a...
+         

+         

+             Labeling: simply a numbering for each time
+             point, telling to which segment it has been assigned. F.ex.
+             1,1,1,2,2,3,3,3,3... first segment: the 3 first time points, second segment:
+             time points 4 & 5... Graphically rendered, with time as horizontal axis, and
+             one color per segment:
+         

+         

+              
+         

+         

+             Cluster: another name for a segment, but
+             seen from the clustering algorithm point of view. A set of vectors
+             that have been grouped together.
+         

+         

+             Templates (landscape maps): the set of n
+             synthetic maps produced by the segmentation that will best represent
+             the data. Also called centroids, they are usually computed as the average of
+             a set of maps. See here f.ex. the 4 template maps given by 4 segments:
+         

+         

+             
+         

+         

+             See also the Segmentation & Fitting page.
+         

+         

+             Tracks
+         

+         

+             Tracks: (or channels, or regular tracks) The display
+             representation of the electrodes' recordings in time.
+         

+         

+             Auxiliary tracks: The tracks of the auxiliary electrodes (like
+             ECG, EOG...), plotted in light blue.
+         

+         

+             Bad tracks: Tracks (usually regular tracks, but auxiliaries
+             are also possible) that have been set as bad by the user. F.ex.
+             noisy, meaningless tracks. The bad tracks are excluded from the
+             computed tracks process, and are plotted in light transparent red.
+         

+         

+             Computed tracks: These are not recorded tracks, but are
+             computed on-line by Cartool, and will appear separately at the bottom
+             of the Eeg display in blue. Presently computed tracks are: GFP,
+             Dissimilarity and Average.
+             Any change on the data, like filtering or setting some tracks as bad
+             will affect the computation, which can be seen in real-time.
+         

+         

+             From top to down, the regular tracks, some auxiliary tracks, then two
+             computed tracks:
+         

+         

+             

+                 
+             

+         

+         

+             Triggers, Markers & Events
+         

+         

+             Trigger: a trigger is a flag already contained 
+                 in
+                 the original Eeg file
+             , usually sent by the stimulation machine
+             when a given event occured (stimuli presentation f.ex.). The
+             user can hide the triggers, but can not delete nor modify them. F.ex.
+             here triggers 1 and 2 were sent when reversing a checkerboard on the screen:

+             
+         

+         

+             Events: in some cases, the recorded file
+             can also contain events sent by the stimulation machine, but which
+             are not triggers by themselves (ie not synchronized to the stimuli
+             presentation). For example initialization events, subject responses
+             from the keypad, reaction times, etc... They too can not be deleted.
+         

+         

+             Marker: a marker is a user defined
+             flag manually set in the Eeg, with any description attached to it.
+             The user can add and delete them as needed, and even generate them
+             through computation (see Markers menu
+             ). They are written in an external file (see .mrk
+                 file format
+             ). F.ex. here two markers were added:

+             
+         

+         

+             Epoch: a small time interval of an
+             EEG. It consists in an origin and two intervals, one before
+             and one after its origin. The origin is usually a trigger from
+             an experiment, and the whole duration will give the size if the ERP computed.
+         

+         

+             There is rarely a single epoch to be considered, but rather a whole
+             serie of them.
+         

+         

+             ERP: Evoked Response Potentials (in case you
+             don't know).
+         

+         

+             Cursor
+         

+         

+             Cursor: the current position in the Eeg, shown in red. Usually
+             it is a single time frame in the Eeg:

+             
+         

+         

+             Extended cursor: the cursor can extend to many time frames.
+             This period of time can be used for averages, or time sequences for
+             the display:

+             
+         

+         

+             Frequency cursor: a cursor to select some frequency range,
+             show in blue. This applies only to frequency files:

+             
+         

+         

+             Time frame: (or time point) while
+             recording the Eeg, each sample is numbered, starting from 0 to N-1, N
+             being the total number of samples. It is therefor an index in the
+             acquisition sequence, but not the time (in
+             milliseconds/seconds/minutes) itself.
+         

+         

+             Sampling frequency: the number of samples per second of the
+             Eeg values. This value makes possible to translate from time frames
+             to milliseconds, which is more understanble and mandatory for some
+             processings (filters f.ex.).
+         

+         

+             MRIs and volumes
+         

+         

+             Isosurface: a mathematical surface
+             which cuts through a volume at a constant value. An isosurface
+             is simply defined by this constant value, telling at which "grey
+             level" the volume is to be cut.

+             Simply put, it is like a hollow veil molded around a volume (the data
+             at a given value).

+             The now classical Marching Cube algorithm is used, with collapsed
+             triangles decimation only. Also, the data are Gaussian filtered
+             before the process, to remove small artifacts, to give a smoother
+             surface and less triangles.
+         

+         

+             Voxel: a volume element (derived from
+             pixel, picture element, that's for the 'x'), the smallest part that
+             can be accessed in a full volume. Voxels are usually indexed by 3
+             coordinates, as they are in 3 dimensions, but these indexes may not
+             have the meaning of X, Y and Z, or whatever you expect them to be...
+         

+         

+             Documents and Views
+         

+         

+             Documents: the actual data read from file are put in a
+             Document. Documents are only numbers in memory, you can't see them.
+             For this purpose, views are attached to them.
+         

+         

+             Views: to see the data, you need at least
+             one view, but you can add as many views as you want, all reflecting
+             the current data from its Document. Views can
+             be of different types, to allow various explorations or analysis.
+             These types are most of the time context sensitive.
+         

+         

+             F.ex. a document with Eeg contents (= simply a matrix of numbers),
+             with 3 views attached at the same time, one view with all 2D Eeg
+             tracks superimposed, one view with 3D Eeg tracks, one view with a 2D
+             interpolated color rendering
+             of a given time frame:
+         

+         

+             

+                 Document

+                 ____

+                 |
+             

+         

+         

+             

+                        
+                 Views
+             

+         

+         

+             OpenGL Graphic
+         

+         

+              ®
+         

+         

+             OpenGL is a standard and very powerful graphic library for 3D
+             rendering, first developped by Silicon Graphics, then transferred to
+             other platforms. OpenGL is evolving, so it has a version number
+             associated with it. Cartool right now is compatible with version 1.1
+             and higher.
+         

+         

+             It is nearly mandatory to have a graphic cards that will accelerate
+             OpenGL operations to have decent performance. Though you can
+             theoretically work without... but I warned you.
+         

+         

+             See www.opengl.org for more informations.
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+     

  
 
\ No newline at end of file
diff --git a/docs/ReferenceGuide/tracks-interpolation.html b/docs/ReferenceGuide/tracks-interpolation.html
index 13dd086f..5ba0dfa1 100644
--- a/docs/ReferenceGuide/tracks-interpolation.html
+++ b/docs/ReferenceGuide/tracks-interpolation.html
@@ -2,169 +2,243 @@
  
   Tracks Interpolation
  
- 
-  

-   Tracks Interpolation

-  

-    

-  

-   What is the use of interpolation?

-  
-  

-   How interpolation works

-  
-  

-   Tracks Interpolation dialog

-  

-   Technical points

-  
-  

-   Results

-  

-   What is the use of interpolation?

-  

-   This tool is used on EEG data for the following purposes:

-  
-  

-    

-  

-   In any of these cases, you will need the electrodes coordinates in an appropriate
-    file.

-  

-   Interpolating bad channels

-  

-   Very often during EEG recording, some tracks are definitely corrupted,
-    but you still have to stick with the setup and the resulting data.

-  

-   To alleviate this fact, one can interpolate these bad channels a posteriori.
-    The values from the bad electrodes are all discarded, and the neighbors 
-   (geometrically speaking) of these bad electrodes are taken to compute 
-   an estimate of what the original values would have been 
-   looking like.

-  

-   Hence the points:

-  
    
-   
  • 
-   
    
-    Interpolating is about re-creating values, please keep this is 
-    mind and avoid it if you can.
    
-   
  • 
-   
    
-    You need a removed electrode to have enough
-     remaining geometrical neighbors to have the most correct 
-    interpolated values.
    
-   
  • 
-   
    
-    Bad electrodes located on the border of the cap, once removed 
-    and "interpolated", are indeed extrapolated,
-     which is not good at all. Usually if too much bad electrodes rely on 
-    the border, you can not recover them safely.
    
-   
  • 
-   
    
-    Seems obvious, but let's remind you that the geometry of the electrodes 
-    has to be known with the best precision, be it from a single subject 
-    or from an average of subjects. Check the symetry and the correct 
-    positions of landmarks.
    
-   

-  

-    

-  

-   See an example of three channels that have been successfully interpolated:

-  

-   

-    

-   

-  

-   

-    

-   

-  

-   Switching to another electrodes system

-  

-   You can transform your data from one electrodes system to another one.
-    This is useful to make data from different systems comparable or to 
-   be processed together.

-  

-   Here are some points worth mentioning:

-  
    
-   
  • 
-   
    
-    You need two electrodes coordinates
-     files, one for each system.
    
-   
  • 
-   
    
-    You can successfully go from a high number of electrodes down to a 
-    lower number of electrodes. The other way round, though 
-    technically working, will of course not create any new 
-    information from the data. This will simply spread the available data 
-    into more channels (you don't gain any resolution).
    
-   
  • 
-   
    
-    Again, watch out for the geometrical borders of 
-    both systems. If they really don't match, the resulting 
-    interpolation will be rather an extrapolation, which is not good 
-    at all for your business.
    
-   
  • 
-   
    
-    If you simply need to remove some electrodes (say the border), you 
-    may consider the faster and easier Export
-     Tracks utility.
    
-   

-  

-    

-  

-   See an example of 125 channels interpolated down to 41 channels:

-  

-   

-    

-    

-   

-  

-   Interpolating bad channels and switching system

-  

-   Well, this is simply the two previous steps done at once: removing 
-   bad channels, and switching to another system.

-  

-   Doing this simultaneously will save you some time, and, more 
-   important (well, it's a matter of choice what is more important 
-   between these two points), will very likely save some little extra 
-   precision in the resulting data.

-  

-   How interpolation works

-  

-   This is a well known method, based mainly on the following articles:

-  

-    

-  
"Mapping of scalp potentials by surface spline interpolation", F. Perrin, J. Pernier, O. Bertrand, M.H. Giard, J.F. Echalier,
+ 
+     

+         

+             Tracks Interpolation
+         

+         

+              
+         

+         

+             What is the use of interpolation?
+         

+         
+         

+             How interpolation works
+         

+         
+         

+             Tracks Interpolation dialog
+         

+         

+             Technical points
+         

+         
+         

+             Results
+         

+         

+             What is the use of interpolation?
+         

+         

+             This tool is used on EEG data for the following purposes:
+         

+         
+         

+              
+         

+         

+             In any of these cases, you will need the electrodes coordinates in an 
+                 appropriate
+                 file
+             .
+         

+         

+             Interpolating bad channels
+         

+         

+             Very often during EEG recording, some tracks are definitely corrupted,
+             but you still have to stick with the setup and the resulting data.
+         

+         

+             To alleviate this fact, one can interpolate these bad channels a posteriori.
+             The values from the bad electrodes are all discarded, and the neighbors
+             (geometrically speaking) of these bad electrodes are taken to compute
+             an estimate of what the original values would have been
+             looking like.
+         

+         

+             Hence the points:
+         

+         
    
+             
  • 
+                 
    
+                     Interpolating is about re-creating values, please keep this is
+                     mind and avoid it if you can.
+                 
    
+             
  • 
+                 
    
+                     You need a removed electrode to have 
+                         
+                             enough
+                             remaining geometrical neighbors
+                         
+                      to have the most correct
+                     interpolated values.
+                 
    
+             
  • 
+                 
    
+                     Bad electrodes located on the border of the cap, once removed
+                     and "interpolated", are indeed extrapolated,
+                     which is not good at all. Usually if too much bad electrodes rely on
+                     the border, you can not recover them safely.
+                 
    
+             
  • 
+                 
    
+                     Seems obvious, but let's remind you that the geometry of the electrodes
+                     has to be known with the best precision, be it from a single subject
+                     or from an average of subjects. Check the symetry and the correct
+                     positions of landmarks.
+                 
    
+         

+         

+              
+         

+         

+             See an example of three channels that have been successfully interpolated:
+         

+         

+             

+                 
+             

+         

+         

+             

+                 
+             

+         

+         

+             Switching to another electrodes system
+         

+         

+             You can transform your data from one electrodes system to another one.
+             This is useful to make data from different systems comparable or to
+             be processed together.
+         

+         

+             Here are some points worth mentioning:
+         

+         
    
+             
  • 
+                 
    
+                     You need two electrodes 
+                         coordinates
+                         files
+                     , one for each system.
+                 
    
+             
  • 
+                 
    
+                     You can successfully go from a 
+                         high number of electrodes down to a
+                         lower number of electrodes
+                     . The other way round, though
+                     technically working, will of course not create any new
+                     information from the data. This will simply spread the available data
+                     into more channels (you don't gain any resolution).
+                 
    
+             
  • 
+                 
    
+                     Again, watch out for the 
+                         
+                             geometrical borders of
+                             both systems
+                         
+                     . If they really don't match, the resulting
+                     interpolation will be rather an extrapolation, which is 
+                         not good
+                         at all
+                      for your business.
+                 
    
+             
  • 
+                 
    
+                     If you simply need to remove some electrodes (say the border), you
+                     may consider the faster and easier 
+                         
+                             Export
+                             Tracks
+                         
+                      utility.
+                 
    
+         

+         

+              
+         

+         

+             See an example of 125 channels interpolated down to 41 channels:
+         

+         

+             

+                 

+                 
+             

+         

+         

+             Interpolating bad channels and switching system
+         

+         

+             Well, this is simply the two previous steps done at once: removing
+             bad channels, and switching to another system.
+         

+         

+             Doing this simultaneously will save you some time, and, more
+             important (well, it's a matter of choice what is more important
+             between these two points), will very likely save some little extra
+             precision in the resulting data.
+         

+         

+             How interpolation works
+         

+         

+             This is a well known method, based mainly on the following articles:
+         

+         

+              
+         

+         
"Mapping of scalp potentials by surface spline interpolation", F. Perrin, J. Pernier, O. Bertrand, M.H. Giard, J.F. Echalier,
 in Electroencephalography and clinical Neurophysiology, 1987, 66: 75-81.
 
 "Spherical splines for scalp potential and current density mapping", F. Perrin, J. Pernier, O. Bertrand, J.F. Echalier,
@@ -173,785 +247,1046 @@ 

 
 "Spline Interpolation of the Scalp EEG", Thomas C. Ferree,
 Technical Note from Electrical Geodesics Inc, See ResearchGate, 2000.

-  
The main loop

-  
For each time frame, do:

-  
    
-   
  • 
-   
    
-    A spline 
-    is computed through the values of the non-excluded electrodes, 
-    by taking into account the geometry of these electrodes.
    
-   
  • 
-   
    
-    The spline is then used to access any point on the surface of the 
-    original geometry, even at location without electrodes (this is 
-    all the interest indeed).
    
-   
  • 
-   
    
-    For all electrodes of the targetted system, retrieve the 
-    values at their locations by simply looking at the spline.
    
-   

-  

-   Which splines are being used

-  

-   You can choose between three different types of spline:

-  
    
-   
  • 
-   
    
-    Surface Spline, after projection on a plane of the electrodes position. Not 
-	recommended if electrodes are not a grid...
    
-   
  • 
-   
    
-    Spherical Spline, after using a unitary spherical version of the 
-    electrodes position.
    
-   
  • 
-   
    
-    3D Spline, the preferred one as it preserves the real geometry of the 
-	electrodes.
    
-   
  • 
-   
    
-    A spherical spline can also be used to compute the Current Source Density.
    
-   

-  

-   Coregistering between two electrodes systems

-  

-   If you switch from one electrodes system to another one, you have to 
-   deal with the very important topic of coregistration. This is 
-   how two different systems are made geometrically superimposable.
-    Most of the time, geometries of different systems are far from 
-   matching each other, so we have to handle that case. See f.ex. two 
-   non-matching geometries of electrodes:

-  

-   

-    

-   

-  

-    

-  

-   There are for sure many different methods, and we sticked to a safe 
-   one: using fiducial electrodes to build an intermediate, 
-   normalized geometrical system. Here is a view of the 
-   international 10-20 system, which were defined as to reliably 
-   relate to the underlying brain structures:

-  

-   

-    

-    

-    (Images taken from: Jaakko Malmivuo & Robert Plonsey

-    Bioelectromagnetism - Principles and Applications of Bioelectric and 
-    Biomagnetic Fields)

-   

-  

-    

-  

-   To define the normalization function (for each electrodes system), we 
-   need to know the following five landmarks (front, sides, back 
-   and top of the head):

-  

-   

-    
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-    

-       

-        

-         Fpz

-        

-       

-        

-          

-       

-        

-         T3

-         (or T7)

-       

-        

-         Cz

-        

-       

-        

-          

-       

-        

-         T4

-         (or T8)

-       

-        

-         Oz

-        

-       

-        

-          

-   

-  

-   More precisely, we need to know the equivalent of these landmarks 
-   in the systems you use. New high-density nets usually don't match 
-   the standard 10-10 (or 10-5) system, so you have to figure out 
-   yourself where these 5 landmarks are. This has to be done carefully, 
-   f.ex. by averaging 10 subjects together, or getting this information 
-   from the company who built the recording machine.

-  

-   If one landmark has no direct equivalent, you can give a set of 
-   electrode which average position will be taken. F.ex. if Oz 
-   does not exist , you could specify "O1 O2" instead.

-  

-    

-  

-   From the 5 landmarks, a 12 parameters affine transform is 
-   derived, which will account for (3 parameters for each line):

-  
    
-   
  • 
-   
    
-    Origin translation
    
-   
  • 
-   
    
-    Rotation
    
-   
  • 
-   
    
-    Scaling (stretching)
    
-   
  • 
-   
    
-    Shearing
    
-   

-  

-    

-  

-   The end result is a centered, unitary 
-   and orthogonal geometrical system, hence called the normalized
-    system.

-  

-   F.ex. see here the original system to be interpolated, then 
-   its normalized version (impossible to see here is the origin 
-   and the overall scaling that are completely different), and a spherical
-    version of the normalized system. Note that the global shape of 
-   the normalized system has been preserved, which is of course not the 
-   case of the spherical one:

-  

-   

-    

-   

-  

-    

-  

-   Using these normalized systems is a snap, f.ex. going from system A 
-   to system B, simply transform to Normalized System A, then transform 
-   back to system B:

-  

-   

-    
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-     
-      
-      
-      
-     
-    

-       

-        

-         Original Coordinate System A

-       

-        

-         Original Coordinate System B

-       

-        

-          |

-       

-        

-         |

-       

-        

-         Normalized Coordinate System A

-       

-        

-          

-         =

-         (equivalent spaces)

-       

-        

-         Normalized Coordinate System B

-   

-  

-    

-  

-   Here is an example of the original
-    system, the target system, and then the original 
-   system finally transformed and superimposed 
-   onto the target system:

-  

-   

-    

-    

-   

-  

-    

-  

-   See also this discussion about the electrodes on 
-   the border, and if it leads or not to extrapolation, and 
-   this note about removing too much electrodes.

-  

-    

-  

-   Finally, we can add that it is not how good the normalized 
-   systems are in absolute (of course, a good transformation is 
-   preferred) that really matters. Rather, it is that by applying the same
-    normalization scheme on both systems, we can transform 
-   coordinates from one system to another. The normalized systems are 
-   just intermediate stages in the whole processing.

-  

-   Tracks Interpolation dialog

-  

-   Call the dialog from Tools
-    | Interpolating EEG files menu, which is context sensitive:

-  
    
-   
  • 
-   
    
-    Called from an EEG file, the processing applies only to this file.
    
-   
  • 
-   
    
-    In any other case, the dialog will operate in Batch mode, requiring 
-    you to later select some files.
    
-   

-  

-    

-  

-   Then the following dialog appears:

-  

-   

-    

-   

-  

-   
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-       
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-       
-     
-     
-       
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-    
-     
-     
-    
-   

-      

-       Tracks Interpolation

-      

-        

-      

-       'From' Space

-      

-       This box deals about the original system.

-      

-       See this discussion about how 'From' and 'To' spaces should geometrically
-        relate to each other.

-      

-       Electrodes coordinates file:

-      

-       Give the file with the 
-       electrodes coordinates.

-      

-       You can Drag & Drop the file directly in this box.

-      

-       Bad electrodes:

-      

-       Optional bad channels to be interpolated.

-      

-       Let the field be empty if you have no bad channels, and just use the 
-	   toolbox to switch
-        to another system.

-      

-       Also see this note about removing too much electrodes.

-      

-       Re-orient, Center & Normalize using Landmarks:

-      

-       We need to re-orient, center
-        and normalize the electrodes coordinates (used in the spline
-        computation, and also to coregister 
-       between two systems).

-       To achieve that, you have to provide the names of the electrodes pointing 
-	   to the front, left, top, right and rear (the 5 landmarks we need). 
-	   Or if you're lucky, Cartool might have already recognized your electrodes system! If this is the case, 
-	   electrodes names will be pre-filled for you.

-      

-       Front / Left / Top / Right / Rear

-      

-       Each of these edit boxes contains the electrodes names used to point in 
-	   the corresponding direction.

-      

-       You can put more than one electrode in one box, in this case, 
-       the average (3D barycenter) of the electrodes position will be 
-       taken. Useful as very often, no one electrode of a given system 
-       exactly matches the 10-10 system.

-      

-       Getting landmarks:

-      

-       Just handy buttons to fill these 5 boxes a little more easily...

-      

-       Cycle into predefined landmarks

-      

-       Force Cartool to cycle into its predefined, known systems, until one 
-       best matches yours.

-      

-       Copy the 'To' landmarks

-      

-       Let's copy the targetted (the 'To') system landmarks.

-      

-       'To' Space

-      

-       This box is used to specify an optional destination system.

-      

-       See this discussion about how 'From' and 'To' spaces should geometrically
-        relate to each other.

-      

-       Destination space is:

-      

-       Choose the behavior of the interpolation.

-      

-       Identical to 'From' Space

-      

-       If you just want to interpolate bad channels,
-        and remain in the same system, check this button.

-      

-       If this is set, you don't need to specify the remaining parameters of 
-       the 'To' box.

-      

-       Another Space:

-      

-       You want to switch to another system, 
-       this is the button to check!

-      

-       Front / Left / Top / Right / Rear

-      

-       Same as per the 'From' case.

-		   

-      

-       Interpolation Method

-      

-       Choose the type of spline.

-      

-       Surface Spline

-      

-       Project the electrodes onto a plane, then use a 2D spline.

-      

-       Not recommend, unless for grid electrodes.

-      

-       Spherical Spline

-      

-       Spline on a centered, unitary sphere. Results are quite good.

-      

-       The spherical version of the original system is directly derived from 
-       the normalized system.

-      

-       3D Spline

-      

-       3D Spline, which accounts for the real geometry of 
-       the head. This is the recommended default spline.

-      

-       Use the normalized system.

-      

-       Curr. Dens. with Spherical Spline

-      

-       Use the spline to compute the Current Source Density (aka Laplacian 
-       of the potential), as in these articles.

-      

-       Spline's Degree:

-      

-       This is the parameter m from the articles
-        cited.

-      

-       See this note.

-      

-       Options

-      

-        

-      

-       Optional filename infix override

-      

-       The exported filenames will have these characters inserted. If empty, the 
-	   infix will be a compound made from all the parameters.

-      

-       Clean up Temp Files

-      

-       Uncheck this box if you want to see by yourself how the centering,
-        the normalization and coregistration have actually been 
-       performed. And cerise sur le gâteau, Cartool even 
-       provides you with 2 more files: the original system finally transformed
-        into the target system, and the target system also transformed 
-       back into the original system. This way you can superimpose 
-       these files and visually check.

-      

-       Open Files Upon Completion

-      

-       Open the interpolated EEG files.

-      

-       Process Current

-      

-       Enabled when called from an EEG. The interpolation applies only to this
-        current file.

-      

-       This button remains disabled until all the parameter 
-       dialogs have received enough (and consistent) informations. If 
-       this is not the case, first check the current dialog: if its 
-       "Next" button is disabled, the problem is in the current 
-       dialog. Otherwise, browse the other dialogs for some missing informations.

-      

-       Batch Process

-      

-       Enabled when not called from an EEG. This will open a dialog for you 
-       to pick the set of files (even from different directories) to 
-       be interpolated.

-      

-       This button remains disabled until all the parameter 
-       dialogs have received enough (and consistent) informations. If 
-       this is not the case, first check the current dialog: if its 
-       "Next" button is disabled, the problem is in the current 
-       dialog. Otherwise, browse the other dialogs for some missing informations.

-      

-       You can Drag & Drop files directly to run the Batch Process!

-      

-       Cancel

-      

-       Quit the dialog.

-      

-       Help

-      

-       Launch the Help to the right page (should be here...).

-  

-   Interpolation - Technical points

-  

-   Re-orienting, centering & normalizing

-  

-   After centering and normalizing, we 
-   should end up with a geometrical system which:

-  
    
-   
  • 
-   
    
-    Origin is on the line Fpz - Oz, intersected by the orthogonal 
-    projection of Cz.
    
-   
  • 
-   
    
-    X axis points to Fpz, and have a unitary length.
    
-   
  • 
-   
    
-    Y axis points to T3 (though it may have been slightly adjusted after 
-    projection of Cz), and have a unitary length.
    
-   
  • 
-   
    
-    Z axis points to Cz, and have a unitary length.
    
-   
  • 
-   
    
-    All three axis are of course orthognal.
    
-   

-  

-   

-    

-   

-  

-   Degree of the spline

-  

-   For a spline of degree m, the actual degree of the 
-   polynomials it is made of is ( m - 1 ).

-  

-   We definitely recommend to use m = 2, that is polynomials of 
-   degree 1, which is very close to a linear interpolation. The advantage is that it will 
-   very unlikely create values that 
-   can exceed the minimum and maximum values of the data. New values will 
-   remain within the range of values of the original data (most of the time).

-  

-   Creating new extrema values could be very detrimental when computing the 
-   source localization. This would produce false brain soures just beneath the 
-   new extrema electrode!

-  

-    

-  

-   Note: as per 2024, spline degree is not editable 
-   from user, and will remain set to 2.

-  

-   Electrodes on the border

-  

-   When interpolating to another system, 
-   you should be sure not to have extrapolation issues. As a rule 
-   of thumb, targetted systems which geometry overflows the original 
-   system are to be avoided. See here a few fine and bad examples (the original 
-   system is in yellow, the targetted system is in blue):

-  

-    

-  
    
-   
  • 
-   
    
-    OK, the original system's border is beyond the target system's border:
    
-   
    
-    
    
-     
    
-    
    
-   
  • 
-   
    
-    NOT OK, the target system's border is beyond the original 
-    system's border:
    
-   
    
-    
    
-     
    
-    
    
-   
  • 
-   
    
-    NOT OK, even though the original system has way more electrodes,
-     their geometrical distribution is not wide enough to 
-    encompass the target system's border:
    
-   
    
-    
    
-     
    
-    
    
-   
  • 
-   
    
-    OK, though the target system has a denser array of electrodes 
-    (smooth out the output):
    
-   
    
-    
    
-     
    
-    
    
-   
  • 
-   
    
-    OK, the original and the target system extents are 
-    geometrically very close to each other (interpolating in the other 
-    direction, from the "blue" to the "yellow" system 
-    could even be tolerable):
    
-   
    
-    
    
-     
    
-    
    
-   

-  

-   Punching a hole in your geometry

-  

-   It is not so advisable to have to remove a bunch of electrodes 
-   (though it might happen due to circumstances) that will punch a 
-   big hole out of your system. Having fewer neighbors to 
-   interpolate from will of course lead to less precise results. See 
-   here just how removing 4 electrodes that are too close to each others 
-   seems a pretty good promise of an awkward interpolation:

-  

-   

-    

-   

-  

-   Noter that you can still remove / interpolate an electrode, say Fpz, 
-   and use its position as a landmark 
-   for the coregistration.

-  

-   Just removing electrodes

-  

-   In this case, using the interpolation is simply an overkill. Consider 
-   the Export Tracks instead...

-  

-   Interpolation - Results

-  
    
-   
  • 
-   
    
-    Interpolated EEG files are written in the same directories as 
-    their sources. File names are inserted with the infix 
-    string, which briefly describes the type of interpolation used. 
-    Currently, only .ep or
-     .eph are outputed.
    
-   
  • 
-   
    
-    The temporary geometry files are written in the same directories as 
-    their original geometry files, which may be different from the EEG 
-    directory. The electrodes coordinates are written as .xyz files.
    
-   
  • 
-   
    
-    Verbose file .vrb 
-    (text), showing all the parameters.
    
-   

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    
+         
The main loop

+         
For each time frame, do:

+         
    
+             
  • 
+                 
    
+                     A spline
+                     is computed through the values of the non-excluded electrodes,
+                     by taking into account the geometry of these electrodes.
+                 
    
+             
  • 
+                 
    
+                     The spline is then used to 
+                         access any point on the surface of the
+                         original geometry
+                     , even at location without electrodes (this is
+                     all the interest indeed).
+                 
    
+             
  • 
+                 
    
+                     For all electrodes of the targetted system, retrieve the
+                     values at their locations by simply looking at the spline.
+                 
    
+         

+         

+             Which splines are being used
+         

+         

+             You can choose between three different types of spline:
+         

+         
    
+             
  • 
+                 
    
+                     Surface Spline, after projection on a plane of the electrodes position. Not
+                     recommended if electrodes are not a grid...
+                 
    
+             
  • 
+                 
    
+                     Spherical Spline, after using a unitary spherical version of the
+                     electrodes position.
+                 
    
+             
  • 
+                 
    
+                     3D Spline, the preferred one as it preserves the real geometry of the
+                     electrodes.
+                 
    
+             
  • 
+                 
    
+                     A spherical spline can also be used to compute the Current Source Density.
+                 
    
+         

+         

+             Coregistering between two electrodes systems
+         

+         

+             If you switch from one electrodes system to another one, you have to
+             deal with the very important topic of coregistration. This is
+             how two different systems are made geometrically superimposable.
+             Most of the time, geometries of different systems are far from
+             matching each other, so we have to handle that case. See f.ex. two
+             non-matching geometries of electrodes:
+         

+         

+             

+                 
+             

+         

+         

+              
+         

+         

+             There are for sure many different methods, and we sticked to a safe
+             one: 
+                 using fiducial electrodes to build an intermediate,
+                 normalized geometrical system
+             . Here is a view of the
+             international 10-20 system, which were defined as to 
+                 reliably
+                 relate to the underlying brain structures
+             :
+         

+         

+             

+                 

+                 

+                 (Images taken from: Jaakko Malmivuo & Robert Plonsey

+                 Bioelectromagnetism - Principles and Applications of Bioelectric and
+                 Biomagnetic Fields)
+             

+         

+         

+              
+         

+         

+             To define the normalization function (for each electrodes system), we
+             need to know the following five landmarks (front, sides, back
+             and top of the head):
+         

+         

+             

+                 
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                 

+                             

+                                 

+                                     Fpz
+                                 

+                             

+                             

+                                 

+                                      
+                         

+                             

+                                 

+                                     T3

+                                     (or T7)
+                         

+                             

+                                 

+                                     Cz
+                                 

+                             

+                             

+                                 

+                                      
+                         

+                             

+                                 

+                                     T4

+                                     (or T8)
+                         

+                             

+                                 

+                                     Oz
+                                 

+                             

+                             

+                                 

+                                      
+                         

+             

+         

+         

+             More precisely, we need to know the 
+                 equivalent of these landmarks
+                 in the systems you use
+             . New high-density nets usually don't match
+             the standard 10-10 (or 10-5) system, so you have to figure out
+             yourself where these 5 landmarks are. This has to be done carefully,
+             f.ex. by averaging 10 subjects together, or getting this information
+             from the company who built the recording machine.
+         

+         

+             If one landmark has no direct equivalent, you can give a set of
+             electrode which average position will be taken. F.ex. if Oz
+             does not exist , you could specify "O1 O2" instead.
+         

+         

+              
+         

+         

+             From the 5 landmarks, a 12 parameters affine transform is
+             derived, which will account for (3 parameters for each line):
+         

+         
    
+             
  • 
+                 
    
+                     Origin translation
+                 
    
+             
  • 
+                 
    
+                     Rotation
+                 
    
+             
  • 
+                 
    
+                     Scaling (stretching)
+                 
    
+             
  • 
+                 
    
+                     Shearing
+                 
    
+         

+         

+              
+         

+         

+             The end result is a centered, unitary
+             and orthogonal geometrical system, hence called the 
+                 
+                     normalized
+                     system
+                 
+             .
+         

+         

+             F.ex. see here the original system to be interpolated, then
+             its normalized version (impossible to see here is the origin
+             and the overall scaling that are completely different), and a 
+                 spherical
+                 version
+              of the normalized system. Note that the global shape of
+             the normalized system has been preserved, which is of course not the
+             case of the spherical one:
+         

+         

+             

+                 
+             

+         

+         

+              
+         

+         

+             Using these normalized systems is a snap, f.ex. going from system A
+             to system B, simply transform to Normalized System A, then transform
+             back to system B:
+         

+         

+             

+                 
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                     
+                 

+                             

+                                 

+                                     Original Coordinate System A
+                         

+                             

+                                 

+                                     Original Coordinate System B
+                         

+                             

+                                 

+                                      |
+                         

+                             

+                                 

+                                     |
+                         

+                             

+                                 

+                                     Normalized Coordinate System A
+                         

+                             

+                                 

+                                      

+                                     =

+                                     (equivalent spaces)
+                         

+                             

+                                 

+                                     Normalized Coordinate System B
+                         

+             

+         

+         

+              
+         

+         

+             Here is an example of the 
+                 original
+                 system
+             , the target system, and then the 
+                 original
+                 system finally transformed and superimposed
+                 onto the target system
+             :
+         

+         

+             

+                 

+                 
+             

+         

+         

+              
+         

+         

+             See also this discussion about the 
+                 electrodes on
+                 the border
+             , and if it leads or not to extrapolation, and
+             this note about removing too much electrodes.
+         

+         

+              
+         

+         

+             Finally, we can add that it is 
+                 not how good the normalized
+                 systems are in absolute
+              (of course, a good transformation is
+             preferred) that really matters. Rather, it is that by applying the 
+                 same
+                 normalization scheme on both systems
+             , we can transform
+             coordinates from one system to another. 
+                 The normalized systems are
+                 just intermediate stages
+              in the whole processing.
+         

+         

+             Tracks Interpolation dialog
+         

+         

+             Call the dialog from 
+                 
+                     Tools
+                     | Interpolating EEG files
+                 
+              menu, which is context sensitive:
+         

+         
    
+             
  • 
+                 
    
+                     Called from an EEG file, the processing applies only to this file.
+                 
    
+             
  • 
+                 
    
+                     In any other case, the dialog will operate in Batch mode, requiring
+                     you to later select some files.
+                 
    
+         

+         

+              
+         

+         

+             Then the following dialog appears:
+         

+         

+             

+                 
+             

+         

+         

+             
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+                 
+                     
+                     
+                 
+             

+                         

+                             Tracks Interpolation
+                     

+                         

+                              
+                     

+                         

+                             'From' Space
+                     

+                         

+                             This box deals about the original system.
+                         

+                         

+                             See this discussion about how 'From' and 'To' spaces should 
+                                 geometrically
+                                 relate to each other
+                             .
+                     

+                         

+                             Electrodes coordinates file:
+                     

+                         

+                             Give the 
+                                 file with the
+                                 electrodes coordinates
+                             .
+                         

+                         

+                             You can Drag & Drop the file directly in this box.
+                     

+                         

+                             Bad electrodes:
+                     

+                         

+                             Optional bad channels to be interpolated.
+                         

+                         

+                             Let the field be empty if you have no bad channels, and just use the
+                             toolbox to 
+                                 switch
+                                 to another system
+                             .
+                         

+                         

+                             Also see this note about removing too much electrodes.
+                     

+                         

+                             Re-orient, Center & Normalize using Landmarks:
+                     

+                         

+                             We need to 
+                                 re-orient, center
+                                 and normalize
+                              the electrodes coordinates (used in the 
+                                 spline
+                                 computation
+                             , and also to coregister
+                             between two systems).
+                         

+                             To achieve that, you have to provide the names of the electrodes pointing
+                             to the front, left, top, right and rear (the 5 landmarks we need).
+                             Or if you're lucky, Cartool might have already recognized your electrodes system! If this is the case,
+                             electrodes names will be pre-filled for you.
+                     

+                         

+                             Front / Left / Top / Right / Rear
+                     

+                         

+                             Each of these edit boxes contains the electrodes names used to point in
+                             the corresponding direction.
+                         

+                         

+                             You can put more than one electrode in one box, in this case,
+                             the average (3D barycenter) of the electrodes position will be
+                             taken. Useful as very often, no one electrode of a given system
+                             exactly matches the 10-10 system.
+                     

+                         

+                             Getting landmarks:
+                     

+                         

+                             Just handy buttons to fill these 5 boxes a little more easily...
+                     

+                         

+                             Cycle into predefined landmarks
+                     

+                         

+                             Force Cartool to cycle into its predefined, known systems, until one
+                             best matches yours.
+                     

+                         

+                             Copy the 'To' landmarks
+                     

+                         

+                             Let's copy the targetted (the 'To') system landmarks.
+                     

+                         

+                             'To' Space
+                     

+                         

+                             This box is used to specify an optional destination system.
+                         

+                         

+                             See this discussion about how 'From' and 'To' spaces should 
+                                 geometrically
+                                 relate to each other
+                             .
+                     

+                         

+                             Destination space is:
+                     

+                         

+                             Choose the behavior of the interpolation.
+                     

+                         

+                             Identical to 'From' Space
+                     

+                         

+                             If you just want to interpolate bad channels,
+                             and remain in the same system, check this button.
+                         

+                         

+                             If this is set, you don't need to specify the remaining parameters of
+                             the 'To' box.
+                     

+                         

+                             Another Space:
+                     

+                         

+                             You want to switch to another system,
+                             this is the button to check!
+                     

+                         

+                             Front / Left / Top / Right / Rear
+                     

+                         

+                             Same as per the 'From' case.
+                         

+                     

+                         

+                             Interpolation Method
+                     

+                         

+                             Choose the type of spline.
+                     

+                         

+                             Surface Spline
+                     

+                         

+                             Project the electrodes onto a plane, then use a 2D spline.
+                         

+                         

+                             Not recommend, unless for grid electrodes.
+                     

+                         

+                             Spherical Spline
+                     

+                         

+                             Spline on a centered, unitary sphere. Results are quite good.
+                         

+                         

+                             The spherical version of the original system is directly derived from
+                             the normalized system.
+                     

+                         

+                             3D Spline
+                     

+                         

+                             3D Spline, which accounts for the real geometry of
+                             the head. This is the recommended default spline.
+                         

+                         

+                             Use the normalized system.
+                     

+                         

+                             Curr. Dens. with Spherical Spline
+                     

+                         

+                             Use the spline to compute the Current Source Density (aka Laplacian
+                             of the potential), as in these articles.
+                     

+                         

+                             Spline's Degree:
+                     

+                         

+                             This is the parameter m from the 
+                                 articles
+                                 cited
+                             .
+                         

+                         

+                             See this note.
+                     

+                         

+                             Options
+                     

+                         

+                              
+                     

+                         

+                             Optional filename infix override
+                     

+                         

+                             The exported filenames will have these characters inserted. If empty, the
+                             infix will be a compound made from all the parameters.
+                     

+                         

+                             Clean up Temp Files
+                     

+                         

+                             Uncheck this box if you want to see by yourself how the 
+                                 centering,
+                                 the normalization and coregistration
+                              have actually been
+                             performed. And cerise sur le gâteau, Cartool even
+                             provides you with 2 more files: the original system finally 
+                                 transformed
+                                 into the target system
+                             , and the target system also transformed
+                             back into the original system. This way you can superimpose
+                             these files and visually check.
+                     

+                         

+                             Open Files Upon Completion
+                     

+                         

+                             Open the interpolated EEG files.
+                     

+                         

+                             Process Current
+                     

+                         

+                             Enabled when called from an EEG. The interpolation applies only to 
+                                 this
+                                 current file
+                             .
+                         

+                         

+                             This button remains 
+                                 disabled until all the parameter
+                                 dialogs have received enough (and consistent) informations
+                             . If
+                             this is not the case, first check the current dialog: if its
+                             "Next" button is disabled, the problem is in the current
+                             dialog. Otherwise, browse the other dialogs for some missing informations.
+                     

+                         

+                             Batch Process
+                     

+                         

+                             Enabled when not called from an EEG. This will open a dialog for you
+                             to pick the set of files (even from different directories) to
+                             be interpolated.
+                         

+                         

+                             This button remains 
+                                 disabled until all the parameter
+                                 dialogs have received enough (and consistent) informations
+                             . If
+                             this is not the case, first check the current dialog: if its
+                             "Next" button is disabled, the problem is in the current
+                             dialog. Otherwise, browse the other dialogs for some missing informations.
+                         

+                         

+                             You can Drag & Drop files directly to run the Batch Process!
+                     

+                         

+                             Cancel
+                     

+                         

+                             Quit the dialog.
+                     

+                         

+                             Help
+                     

+                         

+                             Launch the Help to the right page (should be here...).
+                     

+         

+         

+             Interpolation - Technical points
+         

+         

+             Re-orienting, centering & normalizing
+         

+         

+             After centering and normalizing, we
+             should end up with a geometrical system which:
+         

+         
    
+             
  • 
+                 
    
+                     Origin is on the line Fpz - Oz, intersected by the orthogonal
+                     projection of Cz.
+                 
    
+             
  • 
+                 
    
+                     X axis points to Fpz, and have a unitary length.
+                 
    
+             
  • 
+                 
    
+                     Y axis points to T3 (though it may have been slightly adjusted after
+                     projection of Cz), and have a unitary length.
+                 
    
+             
  • 
+                 
    
+                     Z axis points to Cz, and have a unitary length.
+                 
    
+             
  • 
+                 
    
+                     All three axis are of course orthognal.
+                 
    
+         

+         

+             

+                 
+             

+         

+         

+             Degree of the spline
+         

+         

+             For a spline of degree m, the actual degree of the
+             polynomials it is made of is ( m - 1 ).
+         

+         

+             We definitely recommend to use m = 2, that is polynomials of
+             degree 1, which is very close to a linear interpolation. The advantage is that it will 
+                 very unlikely create values that
+                 can exceed the minimum and maximum values of the data
+             . New values will
+             remain within the range of values of the original data (most of the time).
+         

+         

+             Creating new extrema values could be very detrimental when computing the
+             source localization. This would produce false brain soures just beneath the
+             new extrema electrode!
+         

+         

+              
+         

+         

+             Note: as per 2024, spline degree is not editable
+             from user, and will remain set to 2.
+         

+         

+             Electrodes on the border
+         

+         

+             When interpolating to another system,
+             you should be sure not to have extrapolation issues. As a rule
+             of thumb, targetted systems which geometry overflows the original
+             system are to be avoided. See here a few fine and bad examples (the original
+             system is in yellow, the targetted system is in blue):
+         

+         

+              
+         

+         
    
+             
  • 
+                 
    
+                     OK, the original system's border is beyond the target system's border:
+                 
    
+                 
    
+                     
    
+                         
+                     
    
+                 
    
+             
  • 
+                 
    
+                     NOT OK, the target system's border is beyond the original
+                     system's border:
+                 
    
+                 
    
+                     
    
+                         
+                     
    
+                 
    
+             
  • 
+                 
    
+                     NOT OK, even though the original system has way more electrodes,
+                     their geometrical distribution is not wide enough to
+                     encompass the target system's border:
+                 
    
+                 
    
+                     
    
+                         
+                     
    
+                 
    
+             
  • 
+                 
    
+                     OK, though the target system has a denser array of electrodes
+                     (smooth out the output):
+                 
    
+                 
    
+                     
    
+                         
+                     
    
+                 
    
+             
  • 
+                 
    
+                     OK, the original and the target system extents are
+                     geometrically very close to each other (interpolating in the other
+                     direction, from the "blue" to the "yellow" system
+                     could even be tolerable):
+                 
    
+                 
    
+                     
    
+                         
+                     
    
+                 
    
+         

+         

+             Punching a hole in your geometry
+         

+         

+             It is not so advisable to have to remove a bunch of electrodes
+             (though it might happen due to circumstances) that will 
+                 punch a
+                 big hole out of your system
+             . Having fewer neighbors to
+             interpolate from will of course lead to less precise results. See
+             here just how removing 4 electrodes that are too close to each others
+             seems a pretty good promise of an awkward interpolation:
+         

+         

+             

+                 
+             

+         

+         

+             Noter that you can still remove / interpolate an electrode, say Fpz,
+             and use its position as a landmark
+             for the coregistration.
+         

+         

+             Just removing electrodes
+         

+         

+             In this case, using the interpolation is simply an overkill. Consider
+             the Export Tracks instead...
+         

+         

+             Interpolation - Results
+         

+         
    
+             
  • 
+                 
    
+                     Interpolated EEG files are written in the 
+                         same directories as
+                         their sources
+                     . File names are inserted with the infix
+                     string, which briefly describes the type of interpolation used.
+                     Currently, only .ep 
+                         
+                             or
+                             .eph
+                         
+                      are outputed.
+                 
    
+             
  • 
+                 
    
+                     The temporary geometry files are written in the same directories as
+                     their original geometry files, which may be different from the EEG
+                     directory. The electrodes coordinates are written as .xyz files.
+                 
    
+             
  • 
+                 
    
+                     Verbose file .vrb
+                     (text), showing all the parameters.
+                 
    
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+     

  
 
\ No newline at end of file
diff --git a/docs/ReferenceGuide/windows-general-commands.html b/docs/ReferenceGuide/windows-general-commands.html
index 7d57269f..ce4a6fae 100644
--- a/docs/ReferenceGuide/windows-general-commands.html
+++ b/docs/ReferenceGuide/windows-general-commands.html
@@ -2,551 +2,732 @@
  
   General Commands for all Windows
  
- 
-  

-   General Commands for all Windows

-  

-    

-  

-   All views are now drawn using the OpenGL 
-   library, allowing to show and manipulate objects in a 3D world. Here 
-   are introduced all the commands common to all views.

-  

-   Buttons

-  

-      

-  

-   Mouse

-  

-   All basic mouse operations
Visual hints during mouse operation

-   Rotating
Zooming

-   Polling or Selecting

-   Setting
Moving the clipping planes

-   Setting brightness and contrast

-  

-   Keyboard

-  

-   Rotating
Moving clipping planes

-   Bitmap copy / snapshot

-  

-   Common commands - Buttons

-  

-   Linking to another 3D view  

-  

-   Graphical links allow drawing the contents of other 
-   windows inside a specific one. You can increase the visual message 
-   and check data consistency, through this 3D-consistent inclusion. For 
-   example, linking 2 windows with MRIs, one with a segmented brain and 
-   the other one with a full head would give:

-  

-   

-    +
-     link to

-    =

-    

-   

-  

-   How to do graphical links:

-  
    
-   
  • 
-   
    
-    When clicking on the linking button, a picking arrow appears. By 
-    further clicking with this arrow onto other 3D views, you create 
-    the link to them. That's that simple.
    
-   
  • 
-   
    
-    You can remove individually linked windows by clicking again 
-    on them, or you can remove all links at once by clicking one time in 
-    the original window. Loops of links are not allowed, i.e. linking 
-    view1 to view2, then view2 to view1.
    
-   
  • 
-   
    
-    To quit the linking process, just click outside any 3D window.
    
-   

-  

-   Some remarks:

-  
    
-   
  • 
-   
    
-    The windows'contents are incorporated as they are currently drawn, 
-    with their actual respective settings. You can therefor set 
-    different aspects for each linked views independently, as in the 
-    example above, where the brain is opaque, and the full head is 
-    clipped and transparently rendered. Conversely, any change in one 
-    view will be automatically forwarded to all views linking to it.
    
-   
  • 
-   
    
-    There is no limit as to the number of links allowed, as long 
-    as your graphic card is powerful enough to support this multi-pass 
-    rendering quickly enough for you to work.
    
-   
  • 
-   
    
-    The linked windows are stacked in their incoming order, the 
-    latest being visually "on top". Cartool handles the case of 
-    perfect superimposition (same coordinates) of two windows, in such a 
-    way that the window last linked will be visible. If this is not what 
-    you expect, change the order of the links (clicking the correct 
-    sequence of windows).
    
-   
  • 
-   
    
-    If both the host view and the linked view have clipping
-     planes abilities (f.ex. see here),
-     and if both views have at least one clipping plane active, 
-    then the host view will override the linked view with its own 
-    clipping planes and positions. That is, both views will be 
-    dynamically "synchronized" with the same cutting planes.
    
-   

-  

-   Rendering  

-  

-   Rendering is about changing the modality your data are being 
-   displayed with. By modality, we mean things like transparency
-    versus opacity, or different
-    kind of transparencies, different ways of tiling
-    tracks, etc...

-  

-   Each kind of display has its own set of renderings, which you 
-   can cycle through with this button. Also, most displays of course 
-   include many additional parameters to help refine the current 
-   rendering, but the main switch is still the rendering mode itself.

-  

-   For example, here are some renderings from the MRI
-    / Volume display, showing either opaque slices, a full 
-   transparent surface or a full opaque surface:

-  

-   

-    ,,...

-   

-  

-    

-  

-   Note: nearly all displays include a "void" rendering 
-   in their list of renderings, which actually turns off the display. 
-   This is useful when you have included a window 
-   into another one and want to temporarily hide it while keeping the link.

-  

-   Default orientation(s)  

-  

-   The default is to reset to original 3D orientation. However, 
-   in some cases (MRI, inverse solution...), the buttons will toggle 
-   through a serie of predefined orientations, f.ex. sagittal, 
-   coronal, transverse. See also mouse rotation.

-  

-   Magnifier  

-  

-   By clicking on this button, you enter the magnifier mode, which 
-   graphically zooms the current window. Just move the loupe around the 
-   window to see what's going on there. You can temporarily have a 
-   better idea of a small, or intricate area.

-  

-   Another way to start this mode is by first setting the mouse pointer 
-   where you wish to see more, then press G to magnify. You can again 
-   move the pointer.

-  

-   Quit the magnifier simply by clicking.

-  

-   The magnifier acts purely in 2D, like zooming a picture, and does not 
-   affect any 3D settings.

-  

-   Common commands - Mouse

-  

-   All basic mouse operations

-  

-   

-    
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-     
-      
-      
-      
-      
-     
-    

-       

-        Alternate key

-       

-        

-         Mouse button

-       

-        

-         None

-       

-        

-         Shift

-       

-        

-         Control

-       

-        

-         Left

-       

-        

-         Rotating

-       

-        

-          

-       

-        

-         Zooming

-       

-        

-         Middle

-       

-        

-         Polling or Selecting

-       

-        

-         Setting to bad 

-       

-        

-          

-       

-        

-         Right

-       

-        

-         Brightness / Contrast

-       

-        

-          

-       

-        

-         Moving clipping planes

-   

-  

-    

-  

-   Visual hints during mouse operation

-  

-   Cartool will superimpose on the display a kind of iconic hint 
-   of what the current mouse operation is. This is to help the users 
-   know (and use) better all the mouse functionnalities, which are 
-   designed to improve your experience.

-  

-   These hints may vary according to the current type of display, here 
-   are some examples of the most common ones for operations like 
-   rotation, zoom, brightness (FYI it's the yellowish stuff):

-  

-   

-    

-    

-    

-   

-  

-   Rotating

-  

-   Using the mouse with the left button depressed, you can set 
-   the current rotation of the object. The effect will be different 
-   according to the relative position of the mouse in the window:

-  

-   

-    

-   

-  
    
-   
  • 
-   
    
-    In the central part, you can rotate and turn as if you were 
-    picking the object in 3D.
    
-   
  • 
-   
    
-    In the peripheric part, with a circular movement, the object 
-    will only turn like a 2D picture on the screen. But if you add a 
-    radial component to your movement, it will also add a 3D rotation, as before.
    
-   
  • 
-   
    
-    If you press on Alt key while doing any rotation, all the 
-    angles will step only by 45 degrees each time. You can achieve 
-    clean and precise orthogonal views by starting from the default view, 
-    or by resetting the orientation.
    
-   

-  

-    

-  

-   The visual hints associated, for the 
-   central part of the window, without and with the Alt key:

-  

-   

-    

-   

-  

-   The visual hints associated, for the 
-   peripheric part of the window, without and with the Alt key:

-  

-   

-    

-   

-  

-   Zooming

-  

-   With the mouse left button and the Control key 
-   depressed, you control the 3D zoom of the object, that is how big it 
-   is rendered inside the window:

-  
    
-   
  • 
-   
    
-    move upward to zoom out
    
-   
  • 
-   
    
-    move downward to zoom in
    
-   

-  

-    

-  

-   The visual hints associated, for zooming 
-   out and zooming in:

-  

-   

-    

-   

-  

-   Polling or Selecting

-  

-   While pressing the middle button (yes, under the scroll 
-   wheel!) of the mouse, you can poll or select things 
-   from what you see, and get some informations out of it:

-  
    
-   
  • 
-   
    
-    A 3D cross is drawn at the 3D position where you have pointed to,
    
-   
  • 
-   
    
-    Some textual informations is given below the cross, such as 
-    the 3D coordinates, the Talairach coordinates & names,
-     some value at that point, etc...
    
-   
  • 
-   
    
-    If there are graphical links to other windows, 
-    they will too contribute to the informations displayed.
    
-   
  • 
-   
    
-    The Clipboard 
-    is automatically updated with the same informations as displayed. 
-    You can then Paste them into Excel, a text editor etc... for 
-    later use!
    
-   

-  

-    

-  

-   Note: In the case of the EEG 2D display,
-    the Polling mechanism is overriden to a track
-    selection mechanism.

-  

-    

-  

-   An example of polling into a MRI with Talairach
-    capabilities, showing what the user can see on the screen, and 
-   the resulting 12 fields  from the Clipboard, each separated by a Tab:

-  

-   

-    

-   
45.57  74.68  73.43  18  15  -1  Right Cerebrum  Sub-lobar  Lentiform Nucleus  Gray Matter  Putamen  164

-   Another example, here polling into some Electrode coordinates:

-  

-   

-    

-   
0.41  0.22  0.88                                                                                     17

-   The clipboard is always filled with 12 Tab 
-   separated fields:

-  
    
-   
  • 
-   
    
-    It always starts with the actual x, y, z coordinates of where 
-    you clicked,
    
-   
  • 
-   
    
-    Then the equivalent Talairach coordinates, if available,
    
-   
  • 
-   
    
-    The 5 labels from that Talairach region, if available (à
-     la Talairach Daemon),
    
-   
  • 
-   
    
-    Finally, a value / label related to the underlying object: the 
-    value for MRI, the electrode name for electrodes, etc...
    
-   

-  

-   Any missing piece of information is replaced by a blank Tab, 
-   so you always get 12 fields to help you devise any sort of automation 
-   on the retrieved data.

-  

-    

-  

-   Finally, if another window is graphically linked 
-   into the current one, it can slightly modify the content of what you 
-   clicked onto. For example, it can jump right on the center of the 
-   Solution points, and add the information pertaining to that solution point:

-  

-   

-    

-   

-  

-   Setting

-  

-   With the mouse middle button and the Shift key 
-   depressed, you can optionally set an electrode as bad.
-    Presently this works only within a few views (electrodes 
-   coordinates, potentials display). The result should be 
-   straightforward, by changing the electrode's color.

-  

-   Moving the clipping planes

-  

-   (if clipping planes are available within the current view)

-  

-   With the mouse right button and the Control key 
-   depressed, you can move the clipping planes (can also be done from
-    the keyboard):

-  
    
-   
  • 
-   
    
-    If only 1 clipping plane is active, this is the one that will be 
-    modified. Simply follow the direction of its projected axis on the display.
    
-   
  • 
-   
    
-    If 2 or 3 clipping planes are active, Cartool guesses which one you 
-    want to move by reading the initial motion of your mouse. The 
-    direction you give (the big yellow arrow) will select the axis which 
-    is closer to it (here the Z axis, in blue):
    
-   

-  

-   

-    

-   

-  

-   Release the right mouse if the selected axis is not the one you 
-   expected, and try again. Most of the time, the guess is correct, but 
-   if  the projected axis are very close, it might prove impossible 
-   (here the Y-green and Z-blue axis are too close):

-  

-   

-    

-   

-  

-    

-  

-   The visual hint associated:

-  

-   

-    

-   

-  

-   Setting brightness and contrast

-  

-   With the mouse right button, you can adjust the brightness,
-    if the initial motion is horizontal, leftward decreases 
-   respectively rightward increases it.

-   If the initial motion is vertical, downward decreases and 
-   upward increases the contrast.

-  

-    

-  

-   The visual hints associated:

-  

-   

-    

-    

-   

-  

-   Common commands - Keyboard

-  

-   See here for basic 
-   commands from the keyboard.

-  

-   Rotating

-  

-   By pressing X, Y or Z you rotate the 
-   object, and with Shift depressed, you counter-rotate. See here 
-   for rotating with the mouse.

-  

-   Moving the clipping planes

-  

-   Apart from using the mouse to move the 
-   clipping planes, by first pressing keypad + or - , 
-   then on  X, Y or Z , you can shift the 
-   corresponding plane.

-  

-   Copy as Bitmap (snapshot)

-  

-   To copy the visual content of the current window, use  Edit
-    | Copy as bitmap  or use keyboard Control + C.
-    The snapshot will be placed in the clipboard, ready to be 
-   pasted into whatever other program you use (Word, Powerpoint, 
-   Photoshop, etc..).

-  

-   During the snapshot, Cartool tunes up many parameters to make the 
-   display even more precise and beautiful, f.ex.:

-  
    
-   
  • 
-   
    
-    Using anti-aliasing techniques to remove jagged lines and borders.
    
-    
  • More spatial resolution in some of the objects displayed.
    
-    
  • More color resolution.
    
-    
  • The blue background color is replaced by a white 
-    one, as most of the time, you are going to paste it into a white 
-    page. At the same time, the colors of some "furnitures" 
-    (like axis, borders..) are also adjusted.
    
-   

-  

-   All these features come with a (CPU) cost, and most of the time you 
-   will not notice it. But in some complex windows (MRI shown in slices, 
-   or many linked windows), the 
-   extra time taken can be noticeable. Just be patient, the results will 
-   be worth it.

-  

-   Here is an example of a normal MRI window, with the blue background 
-   (note the jagged borders with the background, and the inner jagged 
-   colors), and the same window once copied, with the white background 
-   (no more jagged borders, and more spatial and color resolution within 
-   the slice):

-  

-   

-    

-   

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    

-  

-    
+ 
+     

+         

+             General Commands for all Windows
+         

+         

+              
+         

+         

+             All views are now drawn using the OpenGL
+             library, allowing to show and manipulate objects in a 3D world. Here
+             are introduced all the commands common to all views.
+         

+         

+             Buttons
+         

+         

+                
+         

+         

+             Mouse
+         

+         

+             All basic mouse operations
Visual hints during mouse operation

+             Rotating
Zooming

+             Polling or Selecting

+             Setting
Moving the clipping planes

+             Setting brightness and contrast
+         

+         

+             Keyboard
+         

+         

+             Rotating
Moving clipping planes

+             Bitmap copy / snapshot
+         

+         

+             Common commands - Buttons
+         

+         

+             Linking to another 3D view  
+         

+         

+             Graphical links allow drawing the contents of other
+             windows inside a specific one. You can increase the visual message
+             and check data consistency, through this 3D-consistent inclusion. For
+             example, linking 2 windows with MRIs, one with a segmented brain and
+             the other one with a full head would give:
+         

+         

+             

+                 +
+                 link to

+                 =

+                 
+             

+         

+         

+             How to do graphical links:
+         

+         
    
+             
  • 
+                 
    
+                     When clicking on the linking button, a picking arrow appears. By
+                     further clicking with this arrow onto other 3D views, you create
+                     the link to them. That's that simple.
+                 
    
+             
  • 
+                 
    
+                     You can remove individually linked windows by clicking again
+                     on them, or you can remove all links at once by clicking one time in
+                     the original window. Loops of links are not allowed, i.e. linking
+                     view1 to view2, then view2 to view1.
+                 
    
+             
  • 
+                 
    
+                     To quit the linking process, just click outside any 3D window.
+                 
    
+         

+         

+             Some remarks:
+         

+         
    
+             
  • 
+                 
    
+                     The windows'contents are incorporated as they are currently drawn,
+                     with their actual respective settings. You can therefor set
+                     different aspects for each linked views independently, as in the
+                     example above, where the brain is opaque, and the full head is
+                     clipped and transparently rendered. Conversely, any change in one
+                     view will be automatically forwarded to all views linking to it.
+                 
    
+             
  • 
+                 
    
+                     There is no limit as to the number of links allowed, as long
+                     as your graphic card is powerful enough to support this multi-pass
+                     rendering quickly enough for you to work.
+                 
    
+             
  • 
+                 
    
+                     The linked windows are stacked in their incoming order, the
+                     latest being visually "on top". Cartool handles the case of
+                     perfect superimposition (same coordinates) of two windows, in such a
+                     way that the window last linked will be visible. If this is not what
+                     you expect, change the order of the links (clicking the correct
+                     sequence of windows).
+                 
    
+             
  • 
+                 
    
+                     If both the host view and the linked view have 
+                         clipping
+                         planes
+                      abilities (f.ex. see here),
+                     and if both views have at least one clipping plane active,
+                     then 
+                         the host view will override the linked view with its own
+                         clipping planes and positions
+                     . That is, both views will be
+                     dynamically "synchronized" with the same cutting planes.
+                 
    
+         

+         

+             Rendering  
+         

+         

+             Rendering is about 
+                 changing the modality your data are being
+                 displayed with
+             . By modality, we mean things like 
+                 transparency
+                 versus opacity
+             , or 
+                 different
+                 kind of transparencies
+             , different ways of 
+                 tiling
+                 tracks
+             , etc...
+         

+         

+             Each kind of display has its own set of renderings, which you
+             can cycle through with this button. Also, most displays of course
+             include many additional parameters to help refine the current
+             rendering, but the main switch is still the rendering mode itself.
+         

+         

+             For example, here are some renderings from the 
+                 MRI
+                 / Volume display
+             , showing either opaque slices, a full
+             transparent surface or a full opaque surface:
+         

+         

+             

+                 ,,...
+             

+         

+         

+              
+         

+         

+             Note: nearly all displays include a "void" rendering
+             in their list of renderings, which actually turns off the display.
+             This is useful when you have included a window
+             into another one and want to temporarily hide it while keeping the link.
+         

+         

+             Default orientation(s)  
+         

+         

+             The default is to reset to original 3D orientation. However,
+             in some cases (MRI, inverse solution...), the buttons will toggle
+             through a serie of predefined orientations, f.ex. sagittal,
+             coronal, transverse. See also mouse rotation.
+         

+         

+             Magnifier  
+         

+         

+             By clicking on this button, you enter the magnifier mode, which
+             graphically zooms the current window. Just move the loupe around the
+             window to see what's going on there. You can temporarily have a
+             better idea of a small, or intricate area.
+         

+         

+             Another way to start this mode is by first setting the mouse pointer
+             where you wish to see more, then press G to magnify. You can again
+             move the pointer.
+         

+         

+             Quit the magnifier simply by clicking.
+         

+         

+             The magnifier acts purely in 2D, like zooming a picture, and does not
+             affect any 3D settings.
+         

+         

+             Common commands - Mouse
+         

+         

+             All basic mouse operations
+         

+         

+             

+                 
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                     
+                         
+                         
+                         
+                         
+                     
+                 

+                             

+                                 Alternate key
+                             

+                             

+                                 

+                                     Mouse button
+                         

+                             

+                                 

+                                     None
+                         

+                             

+                                 

+                                     Shift
+                         

+                             

+                                 

+                                     Control
+                         

+                             

+                                 

+                                     Left
+                         

+                             

+                                 

+                                     Rotating
+                         

+                             

+                                 

+                                      
+                         

+                             

+                                 

+                                     Zooming
+                         

+                             

+                                 

+                                     Middle
+                         

+                             

+                                 

+                                     Polling or Selecting
+                         

+                             

+                                 

+                                     Setting to bad 
+                         

+                             

+                                 

+                                      
+                         

+                             

+                                 

+                                     Right
+                         

+                             

+                                 

+                                     Brightness / Contrast
+                         

+                             

+                                 

+                                      
+                         

+                             

+                                 

+                                     Moving clipping planes
+                         

+             

+         

+         

+              
+         

+         

+             Visual hints during mouse operation
+         

+         

+             Cartool will superimpose on the display a kind of iconic hint
+             of what the current mouse operation is. This is to help the users
+             know (and use) better all the mouse functionnalities, which are
+             designed to improve your experience.
+         

+         

+             These hints may vary according to the current type of display, here
+             are some examples of the most common ones for operations like
+             rotation, zoom, brightness (FYI it's the yellowish stuff):
+         

+         

+             

+                 

+                 

+                 
+             

+         

+         

+             Rotating
+         

+         

+             Using the mouse with the left button depressed, you can set
+             the current rotation of the object. The effect will be different
+             according to the relative position of the mouse in the window:
+         

+         

+             

+                 
+             

+         

+         
    
+             
  • 
+                 
    
+                     In the central part, you can rotate and turn as if you were
+                     picking the object in 3D.
+                 
    
+             
  • 
+                 
    
+                     In the peripheric part, with a circular movement, the object
+                     will only turn like a 2D picture on the screen. But if you add a
+                     radial component to your movement, it will also add a 3D rotation, as before.
+                 
    
+             
  • 
+                 
    
+                     If you press on Alt key while doing any rotation, all the
+                     angles will step only by 45 degrees each time. You can achieve
+                     clean and precise orthogonal views by starting from the default view,
+                     or by resetting the orientation.
+                 
    
+         

+         

+              
+         

+         

+             The visual hints associated, for the
+             central part of the window, without and with the Alt key:
+         

+         

+             

+                 
+             

+         

+         

+             The visual hints associated, for the
+             peripheric part of the window, without and with the Alt key:
+         

+         

+             

+                 
+             

+         

+         

+             Zooming
+         

+         

+             With the mouse left button and the Control key
+             depressed, you control the 3D zoom of the object, that is how big it
+             is rendered inside the window:
+         

+         
    
+             
  • 
+                 
    
+                     move upward to zoom out
+                 
    
+             
  • 
+                 
    
+                     move downward to zoom in
+                 
    
+         

+         

+              
+         

+         

+             The visual hints associated, for zooming
+             out and zooming in:
+         

+         

+             

+                 
+             

+         

+         

+             Polling or Selecting
+         

+         

+             While pressing the middle button (yes, under the scroll
+             wheel!) of the mouse, you can poll or select things
+             from what you see, and get some informations out of it:
+         

+         
    
+             
  • 
+                 
    
+                     A 3D cross is drawn at the 3D position where you have pointed to,
+                 
    
+             
  • 
+                 
    
+                     Some textual informations is given below the cross, such as
+                     the 3D coordinates, the Talairach coordinates & names,
+                     some value at that point, etc...
+                 
    
+             
  • 
+                 
    
+                     If there are graphical links to other windows,
+                     they will too contribute to the informations displayed.
+                 
    
+             
  • 
+                 
    
+                     The 
+                         Clipboard
+                         is automatically updated
+                      with the same informations as displayed.
+                     You can then Paste them into Excel, a text editor etc... for
+                     later use!
+                 
    
+         

+         

+              
+         

+         

+             Note: In the case of the EEG 2D display,
+             the Polling mechanism is overriden to a 
+                 
+                     track
+                     selection mechanism
+                 
+             .
+         

+         

+              
+         

+         

+             An example of polling into a MRI with 
+                 Talairach
+                 capabilities
+             , showing what the user can see on the screen, and
+             the resulting 12 fields  from the Clipboard, each separated by a Tab:
+         

+         

+             

+                 
+             

+         
45.57  74.68  73.43  18  15  -1  Right Cerebrum  Sub-lobar  Lentiform Nucleus  Gray Matter  Putamen  164

+             Another example, here polling into some Electrode coordinates:
+         

+         

+             

+                 
+             

+         
0.41  0.22  0.88                                                                                     17

+             The clipboard is always filled with 12 Tab
+                 separated fields
+             :
+         

+         
    
+             
  • 
+                 
    
+                     It always starts with the actual x, y, z coordinates of where
+                     you clicked,
+                 
    
+             
  • 
+                 
    
+                     Then the equivalent Talairach coordinates, if available,
+                 
    
+             
  • 
+                 
    
+                     The 5 labels from that Talairach region, if available (
+                         à
+                         la
+                      Talairach Daemon),
+                 
    
+             
  • 
+                 
    
+                     Finally, a value / label related to the underlying object: the
+                     value for MRI, the electrode name for electrodes, etc...
+                 
    
+         

+         

+             Any missing piece of information is replaced by a blank Tab,
+             so you always get 12 fields to help you devise any sort of automation
+             on the retrieved data.
+         

+         

+              
+         

+         

+             Finally, if another window is graphically linked
+             into the current one, it can slightly modify the content of what you
+             clicked onto. For example, it can jump right on the center of the
+             Solution points, and add the information pertaining to that solution point:
+         

+         

+             

+                 
+             

+         

+         

+             Setting
+         

+         

+             With the mouse middle button and the Shift key
+             depressed, you can optionally set an electrode as bad.
+             Presently this works only within a few views (electrodes
+             coordinates, potentials display). The result should be
+             straightforward, by changing the electrode's color.
+         

+         

+             Moving the clipping planes
+         

+         

+             (if clipping planes are available within the current view)
+         

+         

+             With the mouse right button and the Control key
+             depressed, you can move the clipping planes (can also be done 
+                 from
+                 the keyboard
+             ):
+         

+         
    
+             
  • 
+                 
    
+                     If only 1 clipping plane is active, this is the one that will be
+                     modified. Simply follow the direction of its projected axis on the display.
+                 
    
+             
  • 
+                 
    
+                     If 2 or 3 clipping planes are active, Cartool guesses which one you
+                     want to move by reading the initial motion of your mouse. The
+                     direction you give (the big yellow arrow) will select the axis which
+                     is closer to it (here the Z axis, in blue):
+                 
    
+         

+         

+             

+                 
+             

+         

+         

+             Release the right mouse if the selected axis is not the one you
+             expected, and try again. Most of the time, the guess is correct, but
+             if  the projected axis are very close, it might prove impossible
+             (here the Y-green and Z-blue axis are too close):
+         

+         

+             

+                 
+             

+         

+         

+              
+         

+         

+             The visual hint associated:
+         

+         

+             

+                 
+             

+         

+         

+             Setting brightness and contrast
+         

+         

+             With the mouse right button, you can adjust the brightness,
+             if the initial motion is horizontal, leftward decreases
+             respectively rightward increases it.

+             If the initial motion is vertical, downward decreases and
+             upward increases the contrast.
+         

+         

+              
+         

+         

+             The visual hints associated:
+         

+         

+             

+                 

+                 
+             

+         

+         

+             Common commands - Keyboard
+         

+         

+             See here for basic
+             commands from the keyboard.
+         

+         

+             Rotating
+         

+         

+             By pressing X, Y or Z you rotate the
+             object, and with Shift depressed, you counter-rotate. See here
+             for rotating with the mouse.
+         

+         

+             Moving the clipping planes
+         

+         

+             Apart from using the 
+                 mouse to move the
+                 clipping planes
+             , by first pressing keypad + or - ,
+             then on  X, Y or Z , you can shift the
+             corresponding plane.
+         

+         

+             Copy as Bitmap (snapshot)
+         

+         

+             To copy the visual content of the current window, use  
+                 
+                     Edit
+                     | Copy as bitmap
+                 
+               or use keyboard Control + C.
+             The snapshot will be placed in the clipboard, ready to be
+             pasted into whatever other program you use (Word, Powerpoint,
+             Photoshop, etc..).
+         

+         

+             During the snapshot, Cartool tunes up many parameters to make the
+             display even more precise and beautiful, f.ex.:
+         

+         
    
+             
  • 
+                 
    
+                     Using anti-aliasing techniques to remove jagged lines and borders.
    
+             
  • More spatial resolution in some of the objects displayed.
    
+             
  • More color resolution.
    
+             
  • 
+                 The blue background color is replaced by a white
+                 one, as most of the time, you are going to paste it into a white
+                 page. At the same time, the colors of some "furnitures"
+                 (like axis, borders..) are also adjusted.
    
+         

+         

+             All these features come with a (CPU) cost, and most of the time you
+             will not notice it. But in some complex windows (MRI shown in slices,
+             or many linked windows), the
+             extra time taken can be noticeable. Just be patient, the results will
+             be worth it.
+         

+         

+             Here is an example of a normal MRI window, with the blue background
+             (note the jagged borders with the background, and the inner jagged
+             colors), and the same window once copied, with the white background
+             (no more jagged borders, and more spatial and color resolution within
+             the slice):
+         

+         

+             

+                 
+             

+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+         

+         

+              
+     

  
 
\ No newline at end of file