Tutorial 1: Create a new protocol

Authors: Francois Tadel, Elizabeth Bock, Sylvain Baillet

Contents

  1. How to read these tutorials
  2. Presentation of the experiment
  3. Brainstorm folders
  4. Starting Brainstorm for the first time
  5. Main interface window
  6. The text is too small
  7. Database structure
  8. Database files
  9. Create your first protocol
  10. Protocol exploration
  11. Set up a backup
  12. Changing the temporary folder
  13. Summary
  14. Roadmap
  15. Moving a database

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.

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.

You will observe minor differences between the screen captures presented in these pages and what you obtain on your computer: different colormaps, different values, etc. The software being constantly improved, some results changed since we produced the illustrations. When the changes are minor and the interpretation of the figures remain the same, we don't necessarily update the images in the tutorial.

If you are interested only in EEG or intra-cranial recordings, don't think that a MEG-based tutorial is not adapted for you. Most of the practical aspects of the data manipulation is very similar in EEG and MEG. First start by reading these introduction tutorials using the MEG example dataset provided, then when you are familiar with the software, go through the tutorial "EEG and Epilepsy" to get some more details about the processing steps that are specific for EEG, or read one of the SEEG/ECOG tutorials available in the section "Other analysis scenarios".

Presentation of the experiment

All the introduction tutorials are based on a simple auditory oddball experiment:

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"


2. Database directory: "brainstorm_db"


3. User directory: ".brainstorm"

Be sure that the paths to the Program, Database, and User directories do not contain special characters. See related forum post.


4. Original data files:

Starting Brainstorm for the first time

  1. If you haven't read the installation instructions, do it now: Installation.

  2. 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> =================================
  3. Read and accept the license file.
  4. Select your Brainstorm database directory (brainstorm_db).

  5. 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.

main_window.gif

The text is too small

If you have a high-resolution screen, the text and icons in the Brainstorm window may not scale properly, leading the interface to be impossible to use. Select the menu File > Edit preferences, the slider at the bottom of the option window lets you increase the ratio of the Brainstorm interface. If it doesn't help, try changing the scaling options in your operating system preferences.

preferences.gif

Database structure

Brainstorm allows you to organize your recordings and analysis with three levels of definition:

Database files

Create your first protocol

  1. Menu File > New protocol.

    menuFile.gif

  2. Edit the protocol name and enter: "TutorialIntroduction".
    It will automatically update the anatomy and datasets paths. Do not edit manually these paths, unless you work with a non-standard database organization and know exactly what you are doing.

  3. 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 acquisition run: Default for all studies
        Different head positions: 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.
        Different number of channels: Another use case is when you have multiple recordings for the same subject that do not have the same number of channels. You cannot share the channel file if the list of channels is not strictly the same for all the files.
        Different cleaning procedures: If you are cleaning artifacts from each acquisition run separately using SSP or ICA projectors, you cannot share the channel file between them (the projectors are saved in the channel file).

      • Yes, use one channel file per subject: Use with caution
        This can be a setting adapted to EEG: the electrodes are in the same position for all the files recorded on one subject, and the number of channels is the same for all the files. However, to use this option, you should not be using SSP/ICA projectors on the recordings, or they should be computed for all the files at once. This may lead to some confusion and sometimes to manipulation errors. For this reason, we decided not to recommend this setting.

      • Yes, use only one global channel file: Not recommended
        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.

  4. 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.

  5. Click on [Create].

    createNewProtocol.gif

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.

Set up a backup

Just like any computer work, your Brainstorm database is always at risk. Software bugs, computer or network crashes and manipulation errors can cause the loss of months of data curation and computation. If the database structure gets corrupted or if you delete or modify accidentally some files, you might not be able to get your data back. There is no undo button!

You created your database, now take some time to find a way to make it safe. If you are not familiar with backuping systems, watch some online tutorials explaining how to set up an automatic daily or weekly backup of your sensitive data. It might seem annoying and useless now, but could save you weeks in the future.

Changing the temporary folder

Some processes need to create temporary files on the hard drive. For example, when epoching MEG/EEG recordings, Brainstorm would first create a temporary folder "import_yymmdd_hhmmss", store all the epochs in it, then move them to the database when the epoching process is completed. The name of the temporary folder indicates its creation time (year/month/day_hour_minutes_seconds). At the end of the process, all the temporary files should be deleted automatically.

The default folder where Brainstorm stores its temporary files is located in the user folder ($HOME/.brainstorm/tmp/), so before importing recordings or calculating large models, you have to make sure you have enough storage space available.

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. In such context, Brainstorm may quickly fill up your limited quota and at some point block your user account.

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. 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.

If a process crashes or is killed before it deletes its temporary files, they would remain in the temporary folder until explicitly deleted. When starting Brainstorm, you would always get offered to delete the previous temporary files: always agree to it, unless they correspond to files generated by another session running simultaneously. Alternatively, you can delete these temporary files by clicking on the Empty button in the same preferences window. More information in the Scripting tutorial.

preferences.gif

Summary

Roadmap

The workflow described in these introduction tutorials include the following steps:

workflow.gif

Advanced

Moving a database

If you are running out of disk space or need to share your database with someone else, you may need to copy or move your protocols to a different folder or drive. Each protocol is handled independently by Brainstorm, therefore in order to move the entire database folder (brainstorm_db), you need to repeat the operations below for each protocol in your database.

Copy the raw files

The original continuous files are not saved in the Brainstorm database. The "Link to raw files" depend on a static path on your local computer and cannot be moved easily to a new computer. You can copy them inside the database before moving the database to a different computer/hard drive using the menu: File > Export protocol > Copy raw files to database. This will make local copies in .bst format of all your original files. The resulting protocol would be larger but portable. This can also be done file by file: right-click > File > Copy to database.

Export a protocol

The easiest option to share a protocol with a collaborator is to export it as a zip file.

Export a subject

Similar as the protocol export, but extracts only the files needed by a single subject.

Move a protocol

To move a protocol to a different location:

  1. [Optional] Set up a backup of your entire brainstorm_db folder if your haven't done it yet. There will be no undo button to press if something bad happens.
  2. [Optional] Copy the raw files to the database (see above)

  3. Unload: Menu File > Delete protocol > Only detach from database.

  4. Move: Move the entire protocol folder to a different location. Remember a protocol folder should be located in the "brainstorm_db" folder and should contain only two subfolders "data" and "anat". Never move or copy a single subject manually.

  5. Load: Menu File > Load protocol > Load from folder > Select the new location of the protocol

  6. If you want to move the entire "brainstorm_db" folder at once, make sure you detach all the protocols in your Brainstorm installation first.

Duplicate a protocol

To duplicate a protocol in the same computer:







Feedback: Comments, bug reports, suggestions, questions
Email address (if you expect an answer):


Tutorials/CreateProtocol (last edited 2023-08-13 09:20:39 by FrancoisTadel)