|
Size: 6406
Comment:
|
Size: 2937
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| = Tutorial 20: Advanced scripting = | = Tutorial 28: Scripting = '''[TUTORIAL UNDER DEVELOPMENT: NOT READY FOR PUBLIC USE] ''' |
| Line 3: | Line 5: |
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. |
|
| Line 6: | Line 10: |
| = From CTF = The main window includes a graphical batching interface that directly benefits from the database explorer: files are organized as a tree of subjects and conditions, and simple drag-and-drop operations readily select files for subsequent batch processing. Most of the Brainstorm features are available through this interface, including pre-processing of the recordings, averaging, time-frequency decompositions, and computing statistics. A full analysis pipeline can be created in a few minutes, saved in the user’s preferences and reloaded in one click, executed directly or exported as a Matlab script. |
== 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. |
| Line 9: | Line 13: |
| The available processes are organized in a plug-in structure. Any Matlab script that is added to the plug-in folder (brainstorm3/toolbox/process/functions/) and has the right format will be automatically detected and made available in the GUI. This mechanism makes the contribution from other developers to Brainstorm very easy. | [Using the individual anatomy of the subjects] |
| Line 11: | Line 15: |
| == Creating a pipeline == | * Script 1: Run FreeSurfer or BrainSuite on the MRI for all the subjects. * Manual: Set the anatomical fiducials in the MRI for each subject. * Option 1: Create and import the subjects one by one. Set the fiducials at the import time. * Option 2: If you have |
| Line 13: | Line 20: |
| === List of processes === 1. Click on Run. The Process selection window appears, with which you can create an analysis pipeline (ie. a list of process that are applied on the selected files one after the other). The first button in the toolbar shows the list of processed that are currently available. If you click on a menu, it's added to the list. |
[Using [[Tutorials/TutWarping|warped templates]]] |
| Line 16: | Line 22: |
| {{http://neuroimage.usc.edu/brainstorm/Tutorials/TutProcesses?action=AttachFile&do=get&target=pipeline1.gif|pipeline1.gif|class="attachment"}} 1. Some menus appear in grey (example: Sources > Spatial smoothing). This means that they are not meant to be applied to the type of data that you have in input, or at the end of the current pipeline. The "spatial smoothing" process may only be run on source files. 1. When you select a process, a list of options specific to this process is shown in the window. * To delete a process: Select it and press the ''Delete'' key, or the big cross in the toolbar. * With the "up arrow" and "down arrow" buttons in the toolbar, you can move up/down a process in the pipeline. 1. Now add the following processes, and set their options: * '''Pre-process > Band-pass filter''': 2Hz - 30Hz * In some processes, you can specify the type(s) of sensors on which you want to apply the process. This way you can for instance apply different filters on the EEG and the MEG, if you have both in the same files. * '''Extract > Extract time''': 40.00ms - 49.60ms, overwrite initial file * This will extract from each file a small time window around the main response peak. * Selecting the overwrite option will replace the previous file (bandpass), with the output of this process (bandpass+extract). This option is usually unselected for the first process in the list, then selected automatically. * '''Average > Average over time''': Overwrite initial file * Compute the average over this small time window. |
[General pipeline] |
| Line 30: | Line 24: |
| {{http://neuroimage.usc.edu/brainstorm/Tutorials/TutProcesses?action=AttachFile&do=get&target=pipeline2.gif|pipeline2.gif|class="attachment"}} 1. Save your pipeline: Click on the last button in the toolbar > Save > New... > Type "process_avg45". |
== Script generation == http://neuroimage.usc.edu/brainstorm/Tutorials/PipelineEditor |
| Line 33: | Line 27: |
| === Saving/exporting a pipeline === The last button in the the toolbar offers a list of menus to save, load and export the pipelines. |
== Script edition == - Add loops, load files, ... |
| Line 36: | Line 30: |
| . {{http://neuroimage.usc.edu/brainstorm/Tutorials/TutProcesses?action=AttachFile&do=get&target=pipeline3.gif|pipeline3.gif|class="attachment"}} | Loops: http://neuroimage.usc.edu/forums/showthread.php?2429-Problem-using-tags |
| Line 38: | Line 32: |
| * '''Load''': List of processes that are saved in the user preferences * '''Load from file''': Import a pipeline from a pipeline_...mat file (previously saved with the menu "Save as Matlab matrix") * '''Save''': Save the pipeline in the user preferences, to be able to access it really fast after * '''Save as Matlab matrix''': Exports the pipeline for a Matlab structure in a .mat file. Allows different users to exchange their analysis pipelines (or a single user between different computers). * '''Generate .m script''': This option generates a human-readable Matlab script that can be re-used for other purposes or modified. * '''Delete''': Remove a pipeline that is saved in the user preferences. * '''Reset options''': Brainstorm saves automatically for each user the options of all the processes. This menu removes all the saved options, and set them back to the default values. |
== 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) |
| Line 46: | Line 38: |
| Here is the Matlab script that is generated automatically for this pipeline. | |
| Line 48: | Line 39: |
| . {{http://neuroimage.usc.edu/brainstorm/Tutorials/TutProcesses?action=AttachFile&do=get&target=script.gif|script.gif|class="attachment"}} . |
|
| Line 51: | Line 40: |
| Click on Ok, in the pipeline window. After a few seconds, you will see two new files in the database, and the "Report viewer" window. | === 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. |
| Line 53: | Line 43: |
| === Report viewer === Each time the pipeline editor is used to executed to run a list of processes, a report is generated and saved in the user home folder (/home/username/reports/). The report viewer shows as an HTML page some of the information saved in this report structure: the date and duration of execution, the list of processes, the input and output files. It reports all the warning and errors that happen during the execution. |
This script is also available in the Brainstorm distribution: '''brainstorm3/toolbox/script/tutorial_raw.m ''' |
| Line 56: | Line 45: |
| The report viewer does not necessarily appear automatically at the end of the last process: it is shown only when more than one processes were executed, or when any of the processes returned an error or a warning. | |
| Line 58: | Line 46: |
| When running processes manually from a script, the calls bst_report(Start, Save, Open) explicitly indicate when the logging of the events should start and stop. | |
| Line 60: | Line 47: |
| You can add images to the reports for quality control using the process "File > Save snapshot". | == Report viewer == Click on Run to start the script. |
| Line 62: | Line 50: |
| {{http://neuroimage.usc.edu/brainstorm/Tutorials/TutProcesses?action=AttachFile&do=get&target=report.gif|output.gif|class="attachment"}} | 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. |
| Line 64: | Line 52: |
| After you close the report window, you can re-open the last report with the main menu of the Brainstorm window: '''File > Report viewer'''. | 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. |
| Line 66: | Line 54: |
| With the buttons in the toolbar, you can go back to the previous reports saved from the same protocol. | |
| Line 68: | Line 55: |
| <<EmbedContent("http://neuroimage.usc.edu/bst/get_prevnext.php?prev=Tutorials/Connectivity")>> | <<EmbedContent("http://neuroimage.usc.edu/bst/get_prevnext.php?prev=Tutorials/Workflows")>> |
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.
[Using the individual anatomy of the subjects]
Script 1: Run FreeSurfer or BrainSuite on the MRI for all the subjects.
- Manual: Set the anatomical fiducials in the MRI for each subject.
- Option 1: Create and import the subjects one by one. Set the fiducials at the import time.
- Option 2: If you have
[Using warped templates]
[General pipeline]
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.