Differences between revisions 19 and 35 (spanning 16 versions)

Full analysis with one script

Authors: Francois Tadel

This tutorial explains how to use the Brainstorm scripting interface to run a full analysis, from the raw recordings to the source reconstruction. It is based on a median nerve stimulation experiment recorded at the Montreal Neurological Institute in 2011 with a CTF MEG 275 system. The sample dataset contains 6 minutes of recordings at 1200Hz for one subject and includes 100 stimulations of each arm.

The tutorial follows the analysis steps detailed in the three advanced tutorials in the category Processing continuous recordings. You should read them before reading this tutorial, to have the explanations that go with the analysis steps.

Contents

Creating the analysis pipeline
Save the pipeline
1. Save in current workspace
2. Export as script
Report viewer
Feedback

Creating the analysis pipeline

Select the menu File > Create new protocol. Name it "TutorialScript" and select the options:

"No, use individual anatomy",
"Yes, use one channel file per subject".

To start building your analysis pipeline, just click on the "Run" button in the Process1 tab. We don't need any file in input, as we are going to select the files to import in the script itself. Then add all the processes listed below. The output of each process is the input of the following one, this is why the order of the processes is important.

Import anatomy > Import anatomy folder

Folder to import: sample_raw/Anatomy
File format: "FreeSurfer folder"
Fiducials: Copy what is indicated below. This is a reason it is usually easier to do this step in interactive mode, and then run only the script starting from the next step.
Input: None; Output: None

Import recordings > Create link to raw file

File to import: Select the folder sample_raw/Data/subj001_somatosensory_20111109_01_AUX-f.ds
Input: None; Output: Raw file

Pre-process > Sinusoid removal (notch)

Input: Raw file ; Output: Raw file (new)

Artifacts > Detect eye blinks

Input: Raw file ; Output: Raw file

Artifacts > Compute SSP: eye blinks

Input: Raw file ; Output: Raw file

Import recordings > Import MEG/EEG : Events

Input: Raw file ; Output: 199 epochs in 2 conditions

Pre-process > Remove DC offset

Input: 199 epochs ; Output: 199 epochs

Pre-process > Add time offset

Input: 199 epochs ; Output: 199 epochs

Sources > Compute noise covariance

Since the epochs are currently selected and pre-processed: we can use them to estimate the noise covariance matrix before we move on with the calculation of the average.

Input: 199 epochs ; Output: 199 epochs

Average > Average files

Input: 199 epochs ; Output: 2 averages

File > Save snapshot: Sensors/MRI registration

Input: 2 averages ; Output: 2 averages

File > Save snapshot: Recordings time series

Input: 2 averages ; Output: 2 averages

Sources > Compute head model

Input: 2 averages ; Output: 2 averages

Sources > Compute sources

Input: 2 averages ; Output: all the source files (1 raw + 2 average + 199 epochs = 202 files)

Save the pipeline

Save in current workspace

Use the menus on top of the pipeline editor to save this list of processes on your computer. The menu "Save > New..." will create an entry readily available in your Brainstorm installation in the Load section of the same menu.

Export as script

Use the menu "Generate .m script" to create a Matlab script that would have the exact same result as running this analysis pipeline from the Brainstorm interface.

This script is also available in the Brainstorm distribution in folder brainstorm3/toolbox/script/tutorial_raw.m

% Script generated by Brainstorm v3.1 (25-Jan-2013)

% Input files
FileNamesA = [];

% Start a new report
bst_report('Start', FileNamesA);

% Process: Import anatomy folder
sFiles = bst_process(...
    'CallProcess', 'process_import_anatomy', ...
    FileNamesA, [], ...
    'subjectname', 'Subject01', ...
    'mrifile', {'C:\Work\RawData\Tutorials\sample_raw\Anatomy', 'FreeSurfer'}, ...
    'nvertices', 15000, ...
    'nas', [126, 215, 138], ...
    'lpa', [58, 136, 121], ...
    'rpa', [197, 138, 118], ...
    'ac', [128, 137, 157], ...
    'pc', [128, 113, 157], ...
    'ih', [128, 125, 216]);

% Process: Create link to raw file
sFiles = bst_process(...
    'CallProcess', 'process_import_data_raw', ...
    sFiles, [], ...
    'subjectname', 'Subject01', ...
    'datafile', {'C:\Work\RawData\Tutorials\sample_raw\Data\subj001_somatosensory_20111109_01_AUX-f.ds', 'CTF'}, ...
    'channelalign', 1);

% Process: Sinusoid removal: 60Hz 120Hz 180Hz
sFiles = bst_process(...
    'CallProcess', 'process_sin_remove', ...
    sFiles, [], ...
    'freqlist', [60, 120, 180], ...
    'sensortypes', 'MEG, EEG', ...
    'reverse', 1);

% Process: Detect eye blinks
sFiles = bst_process(...
    'CallProcess', 'process_evt_detect_eog', ...
    sFiles, [], ...
    'channelname', 'EEG058', ...
    'timewindow', [0, 359.9991667], ...
    'eventname', 'blink');

% Process: SSP EOG: blink
sFiles = bst_process(...
    'CallProcess', 'process_ssp_eog', ...
    sFiles, [], ...
    'eventname', 'blink', ...
    'sensortypes', 'MEG, MEG MAG, MEG GRAD');

% Process: Import MEG/EEG: Events
sFiles = bst_process(...
    'CallProcess', 'process_import_data_event', ...
    sFiles, [], ...
    'subjectname', 'Subject01', ...
    'condition', '', ...
    'eventname', 'left, right', ...
    'timewindow', [0, 359.9991667], ...
    'epochtime', [-0.1, 0.3], ...
    'createcond', 1, ...
    'ignoreshort', 1, ...
    'usectfcomp', 1, ...
    'usessp', 1, ...
    'freq', [], ...
    'baseline', []);

% Process: Remove baseline: [-100ms,-1ms]
sFiles = bst_process(...
    'CallProcess', 'process_baseline', ...
    sFiles, [], ...
    'baseline', [-0.1, -0.0008333333333], ...
    'sensortypes', 'MEG, EEG', ...
    'overwrite', 1);

% Process: Add time offset: -4.20ms
sFiles = bst_process(...
    'CallProcess', 'process_timeoffset', ...
    sFiles, [], ...
    'offset', -0.0042, ...
    'overwrite', 1);

% Process: Compute noise covariance
sFiles = bst_process(...
    'CallProcess', 'process_noisecov', ...
    sFiles, [], ...
    'baseline', [-0.1042, -0.005], ...
    'dcoffset', 1, ...
    'method', 1, ...  % Full noise covariance matrix
    'copycond', 0, ...
    'copysubj', 0);

% Process: Average: By condition (subject average)
sFiles = bst_process(...
    'CallProcess', 'process_average', ...
    sFiles, [], ...
    'avgtype', 3);  % By condition (subject average)

% Process: Snapshot: Sensors/MRI registration
sFiles = bst_process(...
    'CallProcess', 'process_snapshot', ...
    sFiles, [], ...
    'target', 1, ...  % Sensors/MRI registration
    'modality', 1, ...  % MEG (All)
    'orient', 1, ...  % left
    'time', 0, ...
    'contact_time', [0, 0.1], ...
    'contact_nimage', 12, ...
    'comment', 'MEG/MRI Registration');

% Process: Snapshot: Recordings time series
sFiles = bst_process(...
    'CallProcess', 'process_snapshot', ...
    sFiles, [], ...
    'target', 5, ...  % Recordings time series
    'modality', 1, ...  % MEG (All)
    'orient', 1, ...  % left
    'time', 0, ...
    'contact_time', [0, 0.1], ...
    'contact_nimage', 12, ...
    'comment', 'MEG/MRI Registration');

% Process: Compute head model
sFiles = bst_process(...
    'CallProcess', 'process_headmodel', ...
    sFiles, [], ...
    'sourcespace', 1, ...
    'meg', 3, ...  % Overlapping spheres
    'eeg', 3, ...
    'openmeeg', struct(...
         'BemSelect', [0, 0, 1], ...
         'BemCond', [1, 0.0125, 1], ...
         'BemNames', {{'Scalp', 'Skull', 'Brain'}}, ...
         'BemFiles', {{}}, ...
         'isAdjoint', 0, ...
         'isAdaptative', 1, ...
         'isSplit', 0, ...
         'SplitLength', 4000));

% Process: Compute sources
sFiles = bst_process(...
    'CallProcess', 'process_inverse', ...
    sFiles, [], ...
    'method', 1, ...  % Minimum norm estimates (wMNE)
    'wmne', struct(...
         'NoiseCov', [], ...
         'InverseMethod', 'wmne', ...
         'SNR', 3, ...
         'diagnoise', 0, ...
         'SourceOrient', {{'fixed'}}, ...
         'loose', 0.2, ...
         'depth', 1, ...
         'weightexp', 0.5, ...
         'weightlimit', 10, ...
         'regnoise', 1, ...
         'magreg', 0.1, ...
         'gradreg', 0.1, ...
         'eegreg', 0.1, ...
         'fMRI', [], ...
         'fMRIthresh', [], ...
         'fMRIoff', 0.1, ...
         'pca', 1), ...
    'sensortypes', 'MEG, MEG MAG, MEG GRAD, EEG', ...
    'output', 1);  % Kernel only: shared

% Save and display report
ReportFile = bst_report('Save', sFiles);
bst_report('Open', ReportFile);

Report viewer

Click on Run to start the script.

As this process is taking screen captures, do not use your computer for something else at the same time: if another window covers the Brainstorm figures, it will not capture the right images.

At the end, the report viewer is opened to show the status of all the processes, the information messages, the list of input and output files, and the screen captures. The report is saved in your home folder ($home/.brainstorm/reports). If you close this window, you can get it back with the menu File > Report viewer.

-  ⇤ ← Revision 19 as of 2013-01-14 16:14:31 → 
  Size: 10104
  Editor: agrippa
  Comment:
+   ← Revision 35 as of 2014-04-18 16:07:50 → ⇥
  Size: 10326
  Editor: 69
  Comment:
-Deletions are marked like this.
+Additions are marked like this.
 Line 2:
+''Authors: Francois Tadel''
-Line 16:
+Line 18:
-=== Import anatomy > Import FreeSurfer folder ===
 * Subject name: Subject01
 * Folder to import: Select the folder sample_raw/Anatomy
 * Number of vertices (cortex): 15000
+=== Import anatomy > Import anatomy folder ===
 * Folder to import: sample_raw/Anatomy <<BR>>File format: "!FreeSurfer folder"
 Line 23:
-{{attachment:procImportFs.gif}}
+{{attachment:process_import_freesurfer.gif}}
 Line 26:
-Input: None;  Output: Raw file

{{attachment:procLinkRaw.gif|procImportFs.gif}}
+ * File to import: Select the folder sample_raw/Data/subj001_somatosensory_20111109_01_AUX-f.ds
 * Input: None;  Output: Raw file

{{attachment:process_import_data_raw.gif}}
-Line 33:
+Line 34:
-{{attachment:procSin.gif|procImportFs.gif}}
+{{attachment:process_sin_remove.gif}}
-Line 38:
+Line 39:
-{{attachment:procDetectEog.gif|procImportFs.gif}}
+{{attachment:process_evt_detect_eog.gif}}
-Line 43:
+Line 44:
-{{attachment:procSspEog.gif|procImportFs.gif}}
+{{attachment:process_ssp_eog.gif}}
-Line 48:
+Line 49:
-{{attachment:procImportEvt.gif|procImportFs.gif}}
+{{attachment:process_import_data_event.gif}}
-Line 53:
+Line 54:
-{{attachment:procBaseline.gif|procImportFs.gif}}
+{{attachment:process_baseline.gif}}

=== Pre-process > Add time offset ===
Input: 199 epochs ; Output: 199 epochs

{{attachment:process_timeoffset.gif}}
-Line 60:
+Line 66:
-{{attachment:procNoiseCov.gif|procImportFs.gif}}
+{{attachment:process_noisecov.gif}}
-Line 65:
+Line 71:
-{{attachment:procAverage.gif|procImportFs.gif}}
+{{attachment:process_average.gif}}
-Line 70:
+Line 76:
-{{attachment:procSnapReg.gif|procImportFs.gif}}
+{{attachment:process_snapshot.gif}}
-Line 75:
+Line 81:
-{{attachment:procSnapTs.gif|procImportFs.gif}}
+{{attachment:process_snapshot2.gif}}
-Line 80:
+Line 86:
-{{attachment:procHeadmodel.gif|procImportFs.gif}}
+{{attachment:process_headmodel.gif}}
-Line 85:
+Line 91:
-{{attachment:procSources.gif|procImportFs.gif}}
+{{attachment:process_inverse.gif}}
-Line 91:
+Line 97:
-{{attachment:savePipeline.gif|procImportFs.gif}}
+{{attachment:savePipeline.gif}}
-Line 96:
+Line 102:
+This script is also available in the Brainstorm distribution in folder brainstorm3/toolbox/script/tutorial_raw.m
-Line 97:
+Line 105:
-% Script generated by Brainstorm v3.1 (11-Jan-2013)
+% Script generated by Brainstorm v3.1 (25-Jan-2013)
-Line 105:
+Line 113:
-% Process: Import FreeSurfer folder
sFiles = bst_process(...
    'CallProcess', 'process_import_freesurfer', ...
+% Process: Import anatomy folder
sFiles = bst_process(...
    'CallProcess', 'process_import_anatomy', ...
-Line 110:
+Line 118:
-    'mrifile', {'C:\Work\RawData\Tutorials\sample_raw\Anatomy', 'FsDir', [...]
+    'mrifile', {'C:\Work\RawData\Tutorials\sample_raw\Anatomy', 'FreeSurfer'}, ...
-Line 124:
+Line 132:
-    'datafile', {'C:\Work\RawData\Tutorials\sample_raw\Data\EF1982_somatosensory_ [...]
+    'datafile', {'C:\Work\RawData\Tutorials\sample_raw\Data\subj001_somatosensory_20111109_01_AUX-f.ds', 'CTF'}, ...
-Line 140:
+Line 148:
-    'timewindow', [0, 359.999167], ...
+    'timewindow', [0, 359.9991667], ...
-Line 157:
+Line 165:
-    'timewindow', [0, 359.999167], ...
    'epochtime', {[-100, 300], 'ms'}, ...
+    'timewindow', [0, 359.9991667], ...
    'epochtime', [-0.1, 0.3], ...
-Line 166:
+Line 174:
-% Process: Remove baseline: [-100ms,0ms]
+% Process: Remove baseline: [-100ms,-1ms]
-Line 170:
+Line 178:
-    'baseline', [-0.10001, -0.00017], ...
+    'baseline', [-0.1, -0.0008333333333], ...
-Line 174:
+Line 182:
+% Process: Add time offset: -4.20ms
sFiles = bst_process(...
    'CallProcess', 'process_timeoffset', ...
    sFiles, [], ...
    'offset', -0.0042, ...
    'overwrite', 1);
-Line 178:
+Line 193:
-    'baseline', [-0.10001, -0.000843], ...
+    'baseline', [-0.1042, -0.005], ...
-Line 180:
+Line 195:
-    'method', 1, ...
+    'method', 1, ...  % Full noise covariance matrix
-Line 184:
+Line 199:
-% Process: Average: By condition
+% Process: Average: By condition (subject average)
-Line 188:
+Line 203:
-    'avgtype', 3);
+    'avgtype', 3);  % By condition (subject average)
-Line 194:
+Line 209:
-    'target', {1, {'Sensors/MRI registration', [...]
    'modality', {1, {'MEG (All)', [...]
    'orient', {1, {'left', 'right', 'top', 'bottom', 'front', 'back'}}, ...
+    'target', 1, ...  % Sensors/MRI registration
    'modality', 1, ...  % MEG (All)
    'orient', 1, ...  % left
-Line 198:
+Line 213:
-    'contact', '0.000, 0.100, 12', ...
    'comment', 'Registration');
+    'contact_time', [0, 0.1], ...
    'contact_nimage', 12, ...
    'comment', 'MEG/MRI Registration');
-Line 205:
+Line 221:
-    'target', {5, {'Sensors/MRI registration', [...]
    'modality', {1, {'MEG (All)', [...]
    'orient', {1, {'left', 'right', 'top', 'bottom', 'front', 'back'}}, ...
+    'target', 5, ...  % Recordings time series
    'modality', 1, ...  % MEG (All)
    'orient', 1, ...  % left
-Line 209:
+Line 225:
-    'contact', '0.000, 0.100, 12', ...
    'comment', 'Evoked responses');

% Process: Snapshot: Recordings topography (one time)
sFiles = bst_process(...
    'CallProcess', 'process_snapshot', ...
    sFiles, [], ...
    'target', {6, {'Sensors/MRI registration', [...]
    'modality', {1, {'MEG (All)', [...]
    'orient', {1, {'left', 'right', 'top', 'bottom', 'front', 'back'}}, ...
    'time', 0.035, ...
    'contact', '0.000, 0.100, 12', ...
    'comment', 'Evoked responses');
+    'contact_time', [0, 0.1], ...
    'contact_nimage', 12, ...
    'comment', 'MEG/MRI Registration');
-Line 228:
+Line 234:
-    'meg', {3, {'<none>', 'Single sphere', 'Overlapping spheres', 'OpenMEEG BEM'}}, ...
    'eeg', {3, {'<none>', '3-shell sphere', 'OpenMEEG BEM'}}, ...
+    'meg', 3, ...  % Overlapping spheres
    'eeg', 3, ...
-Line 231:
+Line 237:
+         'BemSelect', [0, 0, 1], ...
         'BemCond', [1, 0.0125, 1], ...
         'BemNames', {{'Scalp', 'Skull', 'Brain'}}, ...
-Line 232:
+Line 241:
-         'BemNames', {{'Scalp', 'Skull', 'Brain'}}, ...
         'BemCond', [1, 0.0125, 1], ...
         'BemSelect', [1, 1, 1], ...
-Line 244:
+Line 250:
-    'method', 1, ...
+    'method', 1, ...  % Minimum norm estimates (wMNE)
-Line 264:
+Line 270:
-    'output', 1);
+    'output', 1);  % Kernel only: shared
-Line 273:
+Line 279:
-As this process is taking screen captures, do not use your computer for something else at the same time: if another window covers the Brainstorm figure, it will not capture the right images.

At the end, the report viewer is opened to show the status of all the processes and the screen captures. The report is saved in your home folder ($home/.brainstorm/reports). If you close this window, you can get it back with the menu File > Report viewer.
+As this process is taking screen captures, do not use your computer for something else at the same time: if another window covers the Brainstorm figures, it will not capture the right images.

At the end, the report viewer is opened to show the status of all the processes, the information messages, the list of input and output files, and the screen captures. The report is saved in your home folder ($home/.brainstorm/reports). If you close this window, you can get it back with the menu File > Report viewer.

{{attachment:report1.gif}}

{{attachment:report2.gif}}

== Feedback ==
<<EmbedContent(http://neuroimage.usc.edu/brainstorm3_register/get_feedback.php?Tutorials/TutRawScript)>>

Software

Users

Development

Full analysis with one script

Creating the analysis pipeline

Import anatomy > Import anatomy folder

Import recordings > Create link to raw file

Pre-process > Sinusoid removal (notch)

Artifacts > Detect eye blinks

Artifacts > Compute SSP: eye blinks

Import recordings > Import MEG/EEG : Events

Pre-process > Remove DC offset

Pre-process > Add time offset

Sources > Compute noise covariance

Average > Average files

File > Save snapshot: Sensors/MRI registration

File > Save snapshot: Recordings time series

Sources > Compute head model

Sources > Compute sources

Save the pipeline

Save in current workspace

Export as script

Report viewer

Feedback

Feedback: Comments, bug reports, suggestions, questions

Email address (if you expect an answer):