|
Size: 9467
Comment:
|
Size: 13585
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 2: | Line 2: |
| ''Authors: Francois Tadel, Sylvain Baillet'' | ''Authors: Francois Tadel, Elizabeth Bock, Sylvain Baillet'' |
| Line 5: | Line 5: |
== How to read these tutorials == The goal of these introduction tutorials is to guide you through most of the features of the software. All the pages use the same example dataset. '''The results of one section are most of the time used in the following section''', so read these pages in the correct order. <<TAG(Advanced)>> Some pages may contain too many details for your level of interest or competence. The sections marked as '''[Advanced]''' are not required for you to follow the tutorials until the end. You can skip them the first time you go through the documentation. You will be able to get back to the theory later if you need. '''Please follow first these tutorials with the data we provide'''. This way you will be able to focus on learning how to use the software. It is better to start with some data that is easy to analyze. After going through all the tutorials, you should be comfortable enough with the software to start analyzing your own recordings. If you are interested only in''' EEG or intra-cranial recordings''', don't think that an MEG-based tutorial is not adapted for you. Most of the practical aspects of the data manipulation is very similar in EEG and MEG. Start by reading these introduction tutorials, then go through the tutorial "EEG and Epilepsy" to get some more details about the processing steps that are specific for EEG. == Presentation of the experiment == All the introduction tutorials are based on a simple auditory oddball experiment: * One subject, two acquisition runs of 6 minutes each * Subject stimulated binaurally with intra-aural earphones * Each run contains 200 regular beeps and 40 easy deviant beeps * Recordings with a CTF MEG system with 275 axial gradiometers * Anatomy of the subject: 1.5T MRI, processed with FreeSurfer 5.3 * More details will be given about this dataset along the process. * Full dataset description available on this page: [[DatasetIntroduction|Introduction dataset]] |
|
| Line 23: | Line 45: |
| * Managed automatically by the application: do not move, delete or add files by yourself. | * Managed by the application: do not move, delete or add files by yourself. |
| Line 31: | Line 53: |
| * Created automatically at Brainstorm startup. Typical location:<<BR>> | * Created at Brainstorm startup. Typical location:<<BR>> |
| Line 40: | Line 62: |
| * '''openmeeg/''': OpenMEEG binaries (downloaded automatically when needed) | * '''openmeeg/''': OpenMEEG binaries (automatically downloaded when needed) |
| Line 50: | Line 72: |
| 1. If you haven't read in the installation instructions, do it now: [[Installation]]. | 1. If you haven't read the installation instructions, do it now: [[Installation]]. |
| Line 73: | Line 95: |
| The Brainstorm window described below is designed to remain on one side of the screen. All the space of the desktop that is not covered by this window will be used for opening other figures. Do not try to maximize this window, or the automatic management of the data figures might not work correctly. Keep it on one side of your screen, just large enough so you can read the file names in the database explorer. |
|
| Line 87: | Line 113: |
| * Anatomy: Includes at least an MRI volume and some surfaces extracted from the MRI. * Functional data: Everything that is related with the MEG/EEG acquisition. |
* '''Anatomy''': Includes at least an MRI volume and some surfaces extracted from the MRI. * '''Functional data''': Everything that is related with the MEG/EEG acquisition. |
| Line 101: | Line 127: |
| * Most of the files you see in the database explorer in Brainstorm correspond to files on the hard drive, but there is no one-to-one correspondance. There is extra information stored in each directory, to save properties, comments, default data, links between different items, etc. For this reason, you should not try to manipulate directly the files in the Brainstorm database directory. * The structure of the database is saved in the user preferences, so when you start the program or change protocol, there is no need to read again all the files on the hard drive (which may take some time). * If Brainstorm or Matlab crashes before the database structure is correctly saved, the files that are displayed in the Brainstorm database explorer may differ from what is actually on the disk. When this happens, you can force Brainstorm to rebuild the structure from the files on the hard drive: right-click on the folder to udpate > Reload. |
* Most of the files you see in the database explorer in Brainstorm correspond to files on the hard drive, but there is no one-to-one correspondence. There is extra information stored in each directory, to save properties, comments, default data, links between different items, etc. This is one of the reasons for which you should not try to manipulate directly the files in the Brainstorm database directory. * The structure of the database is saved in the user preferences, so when you start the program or change protocol, there is no need to read again all the files on the hard drive. * If Brainstorm or Matlab crashes before the database structure is correctly saved, the files that are displayed in the Brainstorm database explorer may differ from what is actually on the disk. When this happens, you can force Brainstorm to rebuild the structure from the files on the hard drive: right-click on a folder > '''Reload'''. |
| Line 105: | Line 131: |
| == Create first protocol == 1. Click on the File menu, and select, and select ''New protocol''.<<BR>><<BR>> {{attachment:menuFile.gif}} 1. Edit the protocol name and enter: "TutorialFirstSteps". It will automatically update the paths (''Anatomy path'' and ''Datasets path''). |
== Create your first protocol == 1. Menu File > New protocol.<<BR>><<BR>> {{attachment:menuFile.gif}} 1. Edit the protocol name and enter: "'''TutorialIntroduction'''".<<BR>>It will automatically update the anatomy and datasets paths. |
| Line 109: | Line 135: |
| 1. ''Default properties for the subjects'': * These are the default settings that are used when creating new subjects. It is then possible to override those settings for each subject individually. |
1. Default properties for the subjects: These are the default settings that are used when creating new subjects. It is then possible to override these settings for each subject individually. * '''Default anatomy''': (MRI and surfaces) * '''No, use individual anatomy''':<<BR>>Select when you have individual MRI scans for all the participants of your study. |
| Line 112: | Line 139: |
| * Our objective is to create one subject that uses the default anatomy Colin27, so select the option "''Yes, use protocol's default anatomy''". | * '''Yes, use default anatomy''':<<BR>>Select when you do not have individual scans for the participants, and you would like to use one of the anatomy templates available in Brainstorm. |
| Line 114: | Line 141: |
| * The option ''Default channel file'' is a bit more complicated to understand. It defines at what level we want to define the sensors information (position, orientation, name...) in the database. To make you data management more efficient, you can in some cases use the same ''channel file'' for all the subjects, or for all the folders within one subject. For more information on this option, click on the '''Help button'''. | * '''Default channel file''': (Sensors names and positions) * '''No, use one channel file per condition/run''':<<BR>>Select this if you may have different head positions for one subject. This is usually not the case in EEG, where the electrodes stay in place for all the experiment. In MEG, this is a common setting: one recording session is split in multiple acquisition runs, and the position of the subject's head in the MEG might be different between two runs. |
| Line 116: | Line 144: |
| * In this specific case, this option is not relevant because we are not going to import any recordings. | * '''Yes, use one channel file per subject''':<<BR>>This is a common setting for EEG. The electrodes are in the same position for all the files recorded on one subject. |
| Line 118: | Line 146: |
| 1. Once you get something like the following figure, click on ''Create''.<<BR>><<BR>> {{attachment:createNewProtocol.gif}} | * '''Yes, use only one global channel file''':<<BR>>This is never a recommended setting. It could be used in the case of an EEG study where you use only standard EEG positions on a standard anatomy, but only if you are not doing any advanced source reconstruction. If you share the position of the electrodes between all the subjects, it will also share the source models, which are dependent on the quality of the recordings for each subject. This is complicated to understand at this level, it will make more sense later in the tutorials. 1. In the context of this study, we are going to use the following settings:<<BR>> * '''No, use individual anatomy''': Because we have access to a T1 MRI scan of the subject. * '''No, use one channel file per condition/run''': The typical MEG setup. 1. Click on [Create].<<BR>><<BR>> {{attachment:createNewProtocol.gif}} |
| Line 123: | Line 157: |
| * You can switch between anatomy and functional data with the first three buttons in the toolbar. There are no subjects in the database yet, so the ''Functional data'' views are empty. However, in the ''Anatomy ''view, there is a ''(Default anatomy)'' node; it contains the MRI and the surfaces that can be used by default for the subjects without individual anatomy. | * You can switch between anatomy and functional data with the three buttons just above the database explorer. Read the tooltips of the buttons to see which one does what. * In the ''Anatomy ''view, there is a ''Default anatomy'' node. It contains the ICBM152 anatomy, distributed by the Montreal Neurological Institute (MNI), which is one of the template anatomy folders that are distributed with Brainstorm. * The ''Default anatomy'' node contains the MRI and the surfaces that are used for the subjects without an individual anatomy, or for registering multiple subjects to the same anatomy for group analysis. * There are no subjects in the database yet, so the ''Functional data'' views are empty. |
| Line 125: | Line 162: |
| * The default anatomy used in Brainstorm is based on the ''Colin27 ''MRI volume provided by the Montreal Neurological Institute (MNI): an average of 27 T1 scans of Colin Holmes brain ([[http://www.bic.mni.mcgill.ca/~louis/stx_history.html|more info]]). * The cortex surfaces here were extracted from this average MRI with FreeSurfer. * The inner and outer skull surfaces were generated with Brainstorm. * Display the ''Anatomy ''view, and click on the small "+" to expand the contents of the ''(Default anatomy)'' node. There is one MRI and several surfaces, identified by different icons. * Everything you can do with a node (anatomy files, subjects, protocol) is accessible by right-clicking on it. Take a few minutes to explore all the popup menus by yourself. Don't be afraid of clicking everywhere, at this point you cannot damage anything. |
* Everything you can do with an object in the database explorer (anatomy files, subjects, protocol) is accessible by right-clicking on it. <<BR>><<BR>> |
| Line 136: | Line 165: |
== Changing the temporary folder == If the amount of storage space you have for your user folder is limited (less than 10Gb), you may have to change the temporary folder used by Brainstorm. If you work on a centralized network where all the computers are sharing the same resources, the system admins may impose limited disk quotas to all users and encourage them to use local hard drives instead of the limited and shared user folder. The default temporary folder of Brainstorm is located in your user folder ($HOME/.brainstorm/tmp/), so when you import recordings or calculate large models, it may quickly fill up your limited quota and at some point block your user account. To prevent this, select the menu '''File > Edit preferences''' and set the temporary directory to a folder that is local to your computer, in which you won't suffer from any storage limitation. . {{attachment:preferences.gif||height="293",width="503"}} |
|
| Line 144: | Line 180: |
| * Do not try to maximize the Brainstorm window: keep it small on one side of your screen. <<HTML(<!-- END-PAGE -->)>> |
Tutorial 1: Create a new protocol
Authors: Francois Tadel, Elizabeth Bock, Sylvain Baillet
Contents
How to read these tutorials
The goal of these introduction tutorials is to guide you through most of the features of the software. All the pages use the same example dataset. The results of one section are most of the time used in the following section, so read these pages in the correct order.
Some pages may contain too many details for your level of interest or competence. The sections marked as [Advanced] are not required for you to follow the tutorials until the end. You can skip them the first time you go through the documentation. You will be able to get back to the theory later if you need.
Please follow first these tutorials with the data we provide. This way you will be able to focus on learning how to use the software. It is better to start with some data that is easy to analyze. After going through all the tutorials, you should be comfortable enough with the software to start analyzing your own recordings.
If you are interested only in EEG or intra-cranial recordings, don't think that an MEG-based tutorial is not adapted for you. Most of the practical aspects of the data manipulation is very similar in EEG and MEG. Start by reading these introduction tutorials, then go through the tutorial "EEG and Epilepsy" to get some more details about the processing steps that are specific for EEG.
Presentation of the experiment
All the introduction tutorials are based on a simple auditory oddball experiment:
- One subject, two acquisition runs of 6 minutes each
- Subject stimulated binaurally with intra-aural earphones
- Each run contains 200 regular beeps and 40 easy deviant beeps
- Recordings with a CTF MEG system with 275 axial gradiometers
Anatomy of the subject: 1.5T MRI, processed with FreeSurfer 5.3
- More details will be given about this dataset along the process.
Full dataset description available on this page: Introduction dataset
Brainstorm folders
Brainstorm needs different directories to work properly. If you put everything in the same folder, you would run into many problems. Try to understand this organization before creating a new database.
1. Program directory: "brainstorm3"
- Contains all the program files: Matlab scripts, compiled binaries, templates, etc.
- There is no user data in this folder.
- You can delete it and replace it with a newer version at anytime, your data will be safe.
- Recommended location:
Windows: My documents\brainstorm3
Linux: /home/username/brainstorm3
MacOS: Documents/brainstorm3
2. Database directory: "brainstorm_db"
- Created by user.
- Contains all the Brainstorm database files.
- Managed by the application: do not move, delete or add files by yourself.
- Recommended location:
Windows: My documents\brainstorm_db
Linux: /home/username/brainstorm_db
MacOS: Documents/brainstorm_db
3. User directory: ".brainstorm"
Created at Brainstorm startup. Typical location:
Windows: C:\Documents and Settings\username\.brainstorm
Linux: /home/username/.brainstorm
MacOS: /Users/username/.brainstorm
- Contains:
brainstorm.mat: Brainstorm user preferences.
tmp/: Temporary folder, cleaned every time Brainstorm is started.
You may have to change the location of the temporary folder if you have a limited amount of storage or a limited quota in your home folder.process/: Personal plugins folder.
reports/: Process reports.
openmeeg/: OpenMEEG binaries (automatically downloaded when needed)
templates/: Additional anatomy templates, saved as .zip files.
mex/: Some mex files that have to be recompiled.
4. Original data files:
- Recordings you acquired and you want to process with Brainstorm.
Put them wherever you want but not in any of the previous folders.
Starting Brainstorm for the first time
If you haven't read the installation instructions, do it now: Installation.
Start Brainstorm from Matlab or with the compiled executable.
BST> Starting Brainstorm: BST> ================================= BST> Version: 28-Jan-2015 BST> Checking internet connectivity... ok BST> Compiling main interface files... BST> Emptying temporary directory... BST> Deleting old process reports... BST> Loading configuration file... BST> Initializing user interface... BST> Starting OpenGL engine... hardware BST> Reading plugins folder... BST> Loading current protocol... BST> =================================
- Read and accept the license file.
- Select your Brainstorm database directory (brainstorm_db).
If you do something wrong and don't know how to go back, you can always re-initialize Brainstorm by typing "brainstorm reset" in the Matlab command window, or by clicking on [Reset] in the software preferences (menu File > Edit preferences).
Main interface window
The Brainstorm window described below is designed to remain on one side of the screen. All the space of the desktop that is not covered by this window will be used for opening other figures.
Do not try to maximize this window, or the automatic management of the data figures might not work correctly. Keep it on one side of your screen, just large enough so you can read the file names in the database explorer.
Database structure
Brainstorm allows you to organize your recordings and analysis with three levels of definition:
Protocol
- Group of datasets that have to be processed or displayed together.
- A protocol can include one or several subjects.
Some people would prefer to call this experiment or study.
- You can only open one protocol at a time.
- Your Brainstorm database is a collection of protocols.
Subject
- A person who participated in a given protocol.
- A subject contains two categories of information: anatomy and functional data.
Anatomy: Includes at least an MRI volume and some surfaces extracted from the MRI.
Functional data: Everything that is related with the MEG/EEG acquisition.
- For each subject, it is possible to use either the actual MRI of the person or one of the anatomy templates available in Brainstorm.
Sub-folders
- For each subject, the functional files can be organized in different sub-folders.
- These folders can represent different recordings sessions (aka acquisition runs) or different experimental conditions.
The current structure of the database does not allow more than one level of sub-folders for each subject. It is not possible to organize the files by session AND by condition.
Database files
- The database folder "brainstorm_db" is managed completely from the graphic user interface (GUI).
- All the files in the database have to be imported through the GUI. Do not try to copy files by yourself in the brainstorm_db folder, it won't work.
- Everything in this folder is stored in Matlab .mat format, with the following architecture:
Anatomy data: brainstorm_db/protocol_name/anat/subject_name
Functional data: brainstorm_db/protocol_name/data/subject_name/subfolder/
- Most of the files you see in the database explorer in Brainstorm correspond to files on the hard drive, but there is no one-to-one correspondence. There is extra information stored in each directory, to save properties, comments, default data, links between different items, etc. This is one of the reasons for which you should not try to manipulate directly the files in the Brainstorm database directory.
- The structure of the database is saved in the user preferences, so when you start the program or change protocol, there is no need to read again all the files on the hard drive.
If Brainstorm or Matlab crashes before the database structure is correctly saved, the files that are displayed in the Brainstorm database explorer may differ from what is actually on the disk. When this happens, you can force Brainstorm to rebuild the structure from the files on the hard drive: right-click on a folder > Reload.
Create your first protocol
Menu File > New protocol.
Edit the protocol name and enter: "TutorialIntroduction".
It will automatically update the anatomy and datasets paths.- Default properties for the subjects: These are the default settings that are used when creating new subjects. It is then possible to override these settings for each subject individually.
Default anatomy: (MRI and surfaces)
No, use individual anatomy:
Select when you have individual MRI scans for all the participants of your study.Yes, use default anatomy:
Select when you do not have individual scans for the participants, and you would like to use one of the anatomy templates available in Brainstorm.
Default channel file: (Sensors names and positions)
No, use one channel file per condition/run:
Select this if you may have different head positions for one subject. This is usually not the case in EEG, where the electrodes stay in place for all the experiment. In MEG, this is a common setting: one recording session is split in multiple acquisition runs, and the position of the subject's head in the MEG might be different between two runs.Yes, use one channel file per subject:
This is a common setting for EEG. The electrodes are in the same position for all the files recorded on one subject.Yes, use only one global channel file:
This is never a recommended setting. It could be used in the case of an EEG study where you use only standard EEG positions on a standard anatomy, but only if you are not doing any advanced source reconstruction. If you share the position of the electrodes between all the subjects, it will also share the source models, which are dependent on the quality of the recordings for each subject. This is complicated to understand at this level, it will make more sense later in the tutorials.
In the context of this study, we are going to use the following settings:
No, use individual anatomy: Because we have access to a T1 MRI scan of the subject.
No, use one channel file per condition/run: The typical MEG setup.
Click on [Create].
Protocol exploration
The protocol is created and you can now see it in the database explorer. It is represented by the top-most node in the tree.
- You can switch between anatomy and functional data with the three buttons just above the database explorer. Read the tooltips of the buttons to see which one does what.
In the Anatomy view, there is a Default anatomy node. It contains the ICBM152 anatomy, distributed by the Montreal Neurological Institute (MNI), which is one of the template anatomy folders that are distributed with Brainstorm.
The Default anatomy node contains the MRI and the surfaces that are used for the subjects without an individual anatomy, or for registering multiple subjects to the same anatomy for group analysis.
There are no subjects in the database yet, so the Functional data views are empty.
Everything you can do with an object in the database explorer (anatomy files, subjects, protocol) is accessible by right-clicking on it.
Changing the temporary folder
If the amount of storage space you have for your user folder is limited (less than 10Gb), you may have to change the temporary folder used by Brainstorm. If you work on a centralized network where all the computers are sharing the same resources, the system admins may impose limited disk quotas to all users and encourage them to use local hard drives instead of the limited and shared user folder.
The default temporary folder of Brainstorm is located in your user folder ($HOME/.brainstorm/tmp/), so when you import recordings or calculate large models, it may quickly fill up your limited quota and at some point block your user account. To prevent this, select the menu File > Edit preferences and set the temporary directory to a folder that is local to your computer, in which you won't suffer from any storage limitation.
Summary
- Different folders for:
the program (brainstorm3),
the database (brainstorm_db),
your original recordings.
- Never modify the contents of the database folder by yourself
- Do not put the original recordings in any of the Brainstorm folders, import them with the interface
- Do not try to maximize the Brainstorm window: keep it small on one side of your screen.