= 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 may not work properly.
<>
== Brainstorm folders ==
Brainstorm needs '''different directories''', please try not to put everything at the same place.
'''<
>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 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
''''''<
>'''3. 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.
''''''<
>'''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__'''.
== 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.
* 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 to have more that one level of sub-folders for each subject. Therefore it is not possible to organize the files by session AND by condition.
{{attachment:db.gif}}
== 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. [[Tutorials/TutFirstSteps|Next tutorial]].