= Tutorial 1: Brainstorm architecture =
''Authors: Francois Tadel, Sylvain Baillet''

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

<<TableOfContents(2,2)>>

== 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:<<BR>>
   * '''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.<<BR>>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<<BR>>

== Feedback ==
<<EmbedContent(http://neuroimage.usc.edu/brainstorm3_register/get_feedback.php?Tutorials/BstFolders)>>

== Next ==
It is finally time to start Brainstorm. [[Tutorials/TutFirstSteps|Next tutorial]].