= Brainstorm architecture =
== Brainstorm folders ==
Some more explanations about files and folders.<<BR>>Brainstorm needs '''different directories''', please try not to put everything at the same place, it won't work:

 * '''Program directory: '''"brainstorm3"
  * Contains all the program files: Matlab scripts, Java archives, documentation...
  * No user data in this folder: you can delete it and replace it with a new version, your data will be safe
  * Recommended location:
   * __Windows__: C:\Program Files\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__: C:\Program Files\brainstorm_db
   * __Linux__: /home/username/brainstorm_db
   * __MacOS__: Documents/brainstorm_db
 * '''User directory: '''".brainstorm"
  * Created automatically at Brainstorm startup.
  * Contains the database structure and the temporary folders
  * Typical location:
   * __Windows__: C:\Documents and Settings\username\.brainstorm
   * __Linux__: /home/username/.brainstorm
  * Contains:
   * __brainstorm.mat__: Matlab matrix where the Brainstorm options and database structure are stored.
   * __tmp/__: temporary directory used by some of the Brainstorm functions. Cleaned each time Brainstorm is started
 * '''Original data files''':
  * Recordings and anatomies you acquired and you want to process with Brainstorm.
  * Put them wherever you want''' __but not in any of the previous folders__'''.

== Brainstorm database (concept) ==
Brainstorm toolbox allows you to classify your recordings and analysis with three different levels of definition:

 * '''Protocol'''
  * Some people would prefer to call this ''experiment ''or ''study''.
  * It can designate all the data that were acquired on one or several subjects, with the same objectives (study of a specific cognitive task, epileptic spikes localization, functional differences between two populations).
  * Default data can be defined at the protocol level. If you cannot get the individual MR images of all or some of your subjects, you can use a default anatomy.
  * If you want to localize the sources for an EEG recording but do not know the location of each electrode in space, you can use standardized electrodes positions.
 * '''Subject'''
  * A person who participated in a given protocol.
  * You need two categories of information to define a subject:
   * Files describing the subject's anatomy : MRI and surfaces
   * Functional data files, ie. files that have a temporal dimension or that are related to a precise recording session: EEG / MEG recordings, definition of the sensors, source estimations, statistical results...
 * '''Condition'''
  * 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.

== Brainstorm database (files) ==
 * Brainstorm_db folder created and managed completely from the Brainstorm graphic user interface (GUI)
 * Based on the files/directories architecture:
  * Anatomy data: protocol_name/'''anat'''/subject_name
  * Functional data: 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
  * 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 ==
 * '''Do ''''''not ''''''create the ''''''brainstorm_db'''''' folder in the ''''''brainstorm3 ''''''program folder'''
 * '''Never put your original data files in ''''''brainstorm_db or ''''''brainstorm3 ''''''directories'''
 * '''All the data in Brainstorm database need to be imported via the user interface '''
 * '''This directory is managed completely automatically by the application, do not move or delete the files it contains by yourself'''