Tutorial 28: Scripting
[TUTORIAL UNDER DEVELOPMENT: NOT READY FOR PUBLIC USE]
Authors: Francois Tadel, Elizabeth Bock, Sylvain Baillet
The previous tutorials explained how to use Brainstorm in an interactive way to process one subject with two acquisition runs. In the context of a typical neuroimaging study, you may have tens or hundreds of subjects to process in the same way, it is unrealistic to process all of them manually. Some parts of the analysis pipeline can be processed in batches with no direct supervisions, others require more attention. This tutorial introduces tools and tricks that will help you assemble an efficient analysis pipeline.
What can be automated
The list below contains all the steps of analysis that were detailed in the introduction tutorials, organized in a way that matches the actual work of the person in charge of the analyses. A good approach can be to write separate scripts, and between them perform some verifications and manual adjustments.
Anatomical fiducials: Set NAS/LPA/RPA and compute the MNI transformation for each subject.
Run FreeSurfer or BrainSuite to get cortical surfaces and atlases for all the subjects.
Use the menu File > Batch MRI fiducials: It prompts for the selection of the fiducials for all the subjects and saves a file fiducials.m in each segmentation folder. You will not have to redo this even if you have to start over your analysis from the beginning.
- Create a script that calls the process "Import anatomy folder" in a loop for all the subjects.
Alternatives: Create and import the subjects one by one and set the fiducials at the import time. Or use the default anatomy for all the subjects (or use warped templates).
Script 1: Pre-processing: Loop on the subjects and the acquisition runs.
Create link to raw files: Link all the acquisition runs and the noise recordings to the database
Event markers: Read and group triggers from digital and analog channel, fix stimulation delays
Evaluation: Power spectrum density on all the recordings to evaluate their quality.
Pre-processing: Notch filter, sinusoid removal, band-pass filter.
Evaluation: Power spectrum density on all the recordings to make sure the filters worked well
Cleanup: Delete the links to the original files (the filtered ones are copied in the database).
Detect artifacts: Detect heartbeats, Detect eye blinks, Remove simultaneous
Compute SSP: Heartbeats, Blinks (this selects the first component of each decomposition)
Compute ICA: If you have some types of artifacts you'd like to remove with ICA.
Screenshots: Check the MRI/sensors registration, PSD before and after corrections, SSP.
Export the report to HTML: One report per subject, or one report for all the subjects.
Manual inspection: For each run.
Check the reports: Information messages (number of events, errors and warnings) and screen captures (registration problems, especially obvious noisy channels, incorrect SSP topographies)
- Mark the bad channels
Fix the SSP: For the suspicious runs, open the file viewer, adjust the list of blink and cardiac events, remove and recompute the SSP decompositions, manually select the components.
Detect other artifacts: Run the process on all the runs of all the subjects at once
Mark bad segments: Review the detected artifacts, keep only the ones you want to remove, and then mark the event type as BAD. Review quickly the rest of the file and check that there are no other important artifacts.
Additional SSP: If you find one type of artifact that repeats (typically saccades and SQUID jumps), you can create additional SSP projectors, either with the "SSP: Generic" or directly from the topographies (right-click on the topography figure > Create SSP).
Script 2: Importing
Script generation
http://neuroimage.usc.edu/brainstorm/Tutorials/PipelineEditor
Script edition
- Add loops, load files, ...
Loops: http://neuroimage.usc.edu/forums/showthread.php?2429-Problem-using-tags
File manipulation
- Modify a structure manually: Export to Matlab/Import from Matlab
- File manipulation: file_short, file_fullpath, in_bst_*...
- Documentation of all file structures: point at the appropriate tutorials
- Select files from the database (with bst_get and processes)
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: brainstorm3/toolbox/script/tutorial_raw.m
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.