Tutorial 1: Brainstorm architecture

Authors: Francois Tadel, Sylvain Baillet

You should read this page carefully, in order to understand how the program is organized. If you don't follow a few simple rules reminded at the bottom of the page, Brainstorm will not work properly.

Installation

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

Brainstorm folders

Brainstorm needs different directories, please try not to put everything at the same place:

• 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

• Database directory: "brainstorm_db"

  • Created by user.
  • Contains all the Brainstorm database files.
  • Managed automatically 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

• User directory: ".brainstorm"

  • Created automatically 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 (downloaded automatically when needed)

    • templates/: Additional anatomy templates, saved as .zip files.

    • mex/: Some mex files that have to be recompiled.

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

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.

• 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 or that has a temporal dimension.

• Condition / Run / Folder

  • For each subject, functional files can be classified in different experimental conditions.

  • This level of definition is also used to separate different runs (ie. recording sessions) for the same subject.

    • For example, when adding a new subject, the "Default channel file" option asks you if you have many ("no" option) or only one ("yes" option) recording sessions (i.e. condition) per subject.

Database files

• Brainstorm_db folder is created and managed completely from the Brainstorm graphic user interface (GUI)

• All the files in the database have to be imported through the GUI: (right-click > Import...)

  • Imported files are stored in Matlab format (.mat files) at the appropriate place in the database folder.
  • Do not try to copy files by yourself in the brainstorm_db folder, it won't work
• Based on the files/directories architecture:

  • Anatomy data: brainstorm_db/protocol_name/anat/subject_name

  • Functional data: brainstorm_db/protocol_name/data/subject_name/condition_name/

• Each file you see in the Brainstorm window corresponds to a proper file on the hard drive
  • But the contrary is not necessarily true.
  • There are 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.
• Database structure in memory:

  • A copy of the database structure is saved by Brainstorm in your home directory in .brainstorm/brainstorm.mat

  • So when you start the program or change protocol, there is no need to read again all the files on the hard drive (this may take some time).
  • As a consequence, the files that are displayed in the Brainstorm window may differ from what is actually on the disk.
    • It may happen when some process crashes, or if you move or add some files by yourself in the database folder.

    • If this happens, you will have to reload the current protocol (right-click popup menu > Reload) or the whole database (menu File > Reload database)

To remember

• Different folders for:

  • the program (brainstorm3),

  • the database (brainstorm_db), and

  • your original files.

• 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 graphic interface
  

Feedback

Next

It is finally time to start Brainstorm. ?Next tutorial.