= Brainstorm's Database Structure =
''Authors: Martin Cousineau, Raymundo Cassani''

Understanding the data structures used by Brainstorm is paramount when you want to work on the development of the software. In this page, we will describe the data structures used to store information about a dataset, both in memory and on the hard drive.

<<TableOfContents(2,2)>>

== On the hard drive ==
When you first launch Brainstorm, it asks you to create a Brainstorm database directory (brainstorm_db) on your hard drive. Inside this directory, Brainstorm will create an individual folder for each protocols. This is where the data of a protocol will reside on your hard drive. The database explorer of the software (data tree) is populated directly from the files located in this folder. It has a strict hierarchy, explained in the bullet list below:

 * '''anat''': This is where Anatomy files (e.g. MRI, surfaces) and subject's metadata are stored.
  * One folder per '''subject'''
   * __brainstormsubject.mat__: Metadata of the subject, see ''db_template('subjectmat')''
   * __subjectimage_*.mat__: MRI files, see ''db_template('mrimat')''
   * __tess_*.mat__: Surface files, see ''db_template('surfacemat')''
 * '''data''': This is where Functional files (e.g. channels, recordings) and study's metadata are stored.
  * '''protocol.mat''': All metadata of this protocol, as Matlab structs. See next section for details. Refer to variable ''ProtocolMat ''of function ''db_save''().
  * '''protocol.db''': All metadata of this protocol, as an SQLite database. See next section for details. Refer to ''sql_generate_db''().
  * One folder per '''subject'''
   * One folder per '''study'''
    * __brainstormstudy.mat__: Metadata of the study, see ''db_template('studymat') ''
    * __channel_*.mat__: Channel files, see ''db_template('channelmat')''
    * __data_*.mat__: Data (recording) files, see ''db_template('datamat')''
    * Etc.

All required metadata should always be saved on the hard drive outside of the protocol.mat / protocol.db files, such that if they get corrupted, deleted or one does a fresh reload of the database, there is no loss of information. This is why things like: which cortex file is selected, or which trials are marked as bad are also saved in separate files (brainstormsubject.mat and brainstormstudy.mat).

The filename of each file should always clearly indicate the basic type of the file, hence the required prefixes (e.g. data_*.mat).

The content of the structure of each .mat files is defined in db_template(), with the 'mat' suffix to differenciate from the in-memory metadata structure and the in-momery data structure of each type. For example:

 * db_template(''''surfacemat''''): Structure saved on the hard drive as a surface_*.mat file.
 * db_template(''''loadedsurface''''): Structure saved in memory containing all the data of a loaded surface_*.mat file.
 * db_template(''''surface''''): Structure saved in memory containing all the metadata of a surface_*.mat file, loaded from the protocol.db / protocol.mat file rather than the surface_*.mat file itself.