# custom CSS to remove the numbers from the <ol> tag for table of contents # custom CSS for larger font with backtick # custom CSS for images resize (for mobile) # custom CSS for video resize (for mobile)

<<HTML(<style>.backtick {font-size: 16px;}</style>)>> <<HTML(<style>img {max-width:100%; height:auto;}</style>)>>  <<HTML(<style>abbr {font-weight: bold;}</style>)>>

= Tutorial 1: Create a new protocol =
''Authors: Francois Tadel, Elizabeth Bock, Sylvain Baillet<<BR>><<BR>>''

This is the first tutorial of the ''Get''' '''started'' tutorial series. The goal of these introduction tutorials is to guide you through most of the features of the software. ''The results of one tutorial in the series are often used in the following section, so read these pages in the correct order.'' Moreover,  ''please''' '''follow first these tutorials with the data we provide''. This way you will be able to focus on learning how to use the software. It is better to start with some data that is easy to analyze. After going through all the tutorials, you should be comfortable enough with the software to start analyzing your own recordings.

<<TableOfContents(2,2)>>

== Tutorial conventions ==
This section describes conventions used in [[Tutorials|all the Brainstorm tutorials]].
||<style="text-align:center">'''»''' ||<style="text-align:left">The symbol '''» ''' leads you to a given option in nested menus. For example, '''File»Properties»Option''' points to the open the menu '''File''', then its submenu '''Properties''' and select '''Option'''. ||
||<style="text-align:center">''' bold''' ||<style="text-align:left">Bold text is used to indicate ''elements'' in the graphical user interface (GUI), such as ''window''' '''titles'', ''panel''' '''names'', ''menu''' '''names'', ''menu''' '''items'', ''dialog''' '''boxes'', ''parameter''' '''names'', ''buttons'', etc. Bold text also indicates ''keys'' on the keyboard. ||
||<style="text-align:center">''italic'' ||<style="text-align:left">Italic bold text is used through the tutorials to emphasize relevant ''instructions'', ''concepts'' and ''categories''. ||
||<style="text-align:center">`monospace` ||<style="text-align:left">This font style is used to denote ''names'' and ''paths'' for directories and files. Text in this style also indicates commands. This font style is used to indicate text input that ''needs''' '''to''' '''be''' '''typed'' by the user. ||
||<style="text-align:center"><<Icon(admon-tip.png)>> ||<style="text-align:left">This icon indicates a ''tip'' or ''advice''. ||
||<style="text-align:center"><<Icon(admon-note.png)>> ||<style="text-align:left">This icon indicates a '''''note''''' with important information. ||
||<style="text-align:center"><<Icon(admon-caution.png)>> ||<style="text-align:left">This icons indicates a ''caution'', which informs you of potential actions that can cause irreversibly change or corrupt your data and / or database. ||
||<style="text-align:left"><<TAG(Advanced)>> ||<style="text-align:left">Some pages may contain too many details for your level of interest or competence. The sections marked as '''Advanced''' are not required for you to follow the tutorials until the end. You can skip them the first time you go through the documentation. You will be able to get back to the theory later if you need. ||




== How to read these tutorials ==
The  goal of these introduction tutorials is to guide you through most of  the features of the software. All the pages use the same example  dataset. ''The results of one section are most of the time used in the following section'', so read these pages in the correct order.

''Please follow first  these tutorials with the data we provide''.  This way you will be able to  focus on learning how to use the  software. It is better to start with some data that is easy to analyze.  After going through all the tutorials, you should be comfortable enough  with the software to start analyzing your own recordings.

You may observe ''minor differences''  between the screen captures presented in these pages and what you  obtain on your computer: different colormaps, different values, etc. The  software being constantly improved, some results changed since we  produced the illustrations. When the changes are minor and the  interpretation of the figures remain the same, we don't necessarily  update the images in the tutorial.

If you are interested only in ''EEG'' or ''intra-cranial recordings'',  do not think that these MEG-based introduction tutorials is not adapted for you. Most of  the practical aspects of the data manipulation are very similar in ''EEG''  and ''MEG''. First start by reading and following these introduction tutorials using the  MEG example dataset provided, then when you are familiar with the  software, go through the tutorial [[https://neuroimage.usc.edu/brainstorm/Tutorials/Epilepsy|EEG and Epilepsy]]  to get more details about the processing steps that are specific  for EEG, or read one of the SEEG/ECOG tutorials available in the section  "Other analysis scenarios".

== Presentation of the experiment ==
All the introduction tutorials are based on a simple auditory oddball experiment: ''' '''

 * One subject, two acquisition runs of 6 minutes each. ''' '''
 * Subject stimulated binaurally with intra-aural earphones. ''' '''
 * Each run contains 200 regular beeps and 40 easy deviant beeps. ''' '''
 * Recordings with a CTF MEG system with 275 axial gradiometers. ''' '''
 * Anatomy of the subject: 1.5T MRI, processed with FreeSurfer 5.3. ''' '''
 * More details will be given about this dataset along the process. ''' '''
 * Full dataset description available on this page: [[DatasetIntroduction|Introduction dataset]]. ''' '''

== Brainstorm folders ==
Brainstorm needs ''different directories''  to work properly. If you put everything in the same folder, you would  run into many problems. Try to understand this organization before  creating a new database. ''' '''

<<BR>>'''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` ''' '''

<<BR>>'''2. Database directory''': ` brainstorm_db`

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

<<BR>>'''3. User directory''': ` .brainstorm`

 * Created at first 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.
  * `process/`: Personal plugins folder.
  * `reports/`: Process reports.
  * `openmeeg/`: OpenMEEG binaries (automatically downloaded when needed).
  * `templates/`: Additional anatomy templates, saved as `.zip` files.
  * `mex/`: Some `.mex` files that have to be recompiled.
  * `tmp/` : Temporary folder, cleaned every time Brainstorm is started.<<BR>>

{{{#!wiki note
'''Note:''' 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.
}}}
<<BR>>'''4. Original data files''':

 * Recordings you acquired and you want to process with Brainstorm.

{{{#!wiki caution
Put your '''''Original data files''''' wherever you want, except in the '''''Program directory''''', the '''''Database directory''''' or the '''''User directory'''''; otherwise Brainstorm, its dataset and/or your data can be corrupted.
}}}
== Starting Brainstorm for the first time ==
 1. If you haven't read the installation instructions, do it now: [[Installation]]. ''' '''

 1. Start Brainstorm from Matlab or with the compiled executable.<<BR>> ''' '''
 {{{
BST> Starting Brainstorm:
BST> =================================
BST> Version: 28-Jan-2015
BST> Checking internet connectivity... ok
BST> Compiling main interface files...
BST> Emptying temporary directory...
BST> Deleting old process reports...
BST> Loading configuration file...
BST> Initializing user interface...
BST> Starting OpenGL engine... hardware
BST> Reading plugins folder...
BST> Loading current protocol...
BST> =================================
}}}
 1. Read and accept the license file.
 1. Select your Brainstorm database directory (`brainstorm_db`).

{{{#!wiki tip
If you do something wrong and do not know how to go back, you can always '''''re-initialize''''' Brainstorm by typing ` brainstorm reset ` in the Matlab  '''Command Window''', or by clicking on '''Reset''' in Brainstorm preferences (menu '''File»Edit preferences''').
}}}
== Main interface window ==
The main Brainstorm window described below is designed to remain on one side of  the screen. All the space of the desktop that is not covered by this window will be used for opening other figures.

{{{#!wiki note
Do not try to maximize this window, or the automatic management of the  data figures might not work correctly. Keep it on one side of your  screen, just large enough so you can read the file names in the database  explorer.
}}}
 . {{attachment:main_window.gif}}

{{{#!wiki tip
'''Tooltips''' <<BR>> If you have doubts about an element in the Brainstorm interface, places your mouse pointer over it and a text box will display information about the element.
}}}
== The text is too small ==
If you have a high-resolution screen, the text and icons in the Brainstorm may not scale properly, leading the interface to be impossible to use. This can be adjusted with the '''Interface scaling (%)''' slider in '''File»Edit preferences''' or {{attachment:iconProperties.gif}}  in the main Brainstorm window.

 . {{attachment:preferences.gif||width="500",height="375"}}

== 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''.
  * ''Only one protocol'' can be opened at a time.
  * Your Brainstorm database is a collection of protocols.
 * '''Subject'''
  * A person who participated in a given protocol.
  * A subject contains two categories of information: ''anatomy'' and ''functional''' '''data''.<<BR>> '''Anatomy''': Includes at least an MRI volume and some surfaces extracted from the MRI. <<BR>> '''Functional data''': Everything that is related with the MEG/EEG acquisition. <<BR>>
  * 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 allows ''only one'' level of  sub-folders for each subject. Thus, it is not possible to organize the files by session AND by condition.<<BR>><<BR>> {{attachment:db.gif}}

== Database files ==
 * The database directory ` brainstorm_db` is managed completely from the graphic user interface (GUI).
 * All the files in the database ''must'' to be imported through the GUI. Do not try to copy files by yourself in the brainstorm_db folder, it won't  work.
 * Everything in this folder is stored in Matlab `.mat` format, with the following architecture:
  * '''Anatomy data''':<<BR>> `brainstorm_db/protocol_name/`'''`anat`'''`/subject_name`
  * '''Functional data''':<<BR>> `brainstorm_db/protocol_name/`'''`data`'''`/subject_name/subfolder/`
 * Most  of the files you see in the database explorer in Brainstorm correspond  to files on the hard drive, but there is no one-to-one correspondence.  There is extra information stored in each directory, to save   properties, comments, default data, links between different items, etc.  This is one of the reasons for which you should not try to manipulate  directly the files in the Brainstorm database directory. ''' '''
 * The  structure of the database is saved in the user preferences, so when you  start the program or change protocol, there is no need to  read again  all the files on the hard drive. ''' '''
 * If  Brainstorm or Matlab crashes before the database structure is correctly  saved, the files that are displayed in the Brainstorm database explorer  may differ from what is actually on the disk. When this happens, you can  force Brainstorm to rebuild the structure from the files on the hard  drive: right-click on a folder > '''Reload'''. ''' '''

== Create your first protocol ==
 1. Click on '''File»New protocol'''. The '''Create new protocol''' will appear, here you need to introduce the properties of the new protocol. <<BR>><<BR>> {{attachment:menuFile.gif}}

 1. '''Protocol definition''': Provide the '''Protocol name''', enter: `TutorialIntroduction`.<<BR>>It will automatically update the anatomy and datasets paths. ''Do not edit manually'' these paths, unless you work with a non-standard database organization and know exactly what you are doing.

 1. '''Default properties for the subjects''': These are the default settings that are used when creating new subjects. It is then possible to override these  settings for each subject individually.
  * '''Default anatomy''': (MRI and surfaces)
   * '''No, use individual anatomy''':<<BR>>Select when you have individual MRI scans for all the participants of your study.
   * '''Yes, use default anatomy''':<<BR>>Select  when you do not have individual scans for the participants, and you  would like to use one of the anatomy templates available in Brainstorm.

  * '''Default channel file''': (Sensors names and positions)
   * '''No, use one channel file per acquisition run''':<<BR>>__Different head positions__:  Select this if you may have different head positions for one subject.  This is usually not the case in EEG, where the electrodes stay in place  for all the experiment. In MEG, this is a common setting: one recording  session is split in multiple acquisition runs, and the position of the  subject's head in the MEG might be different between two runs.<<BR>>__Different number of channels__:  Another use case is when you have multiple recordings for the same  subject that do not have the same number of channels. You cannot share  the channel file if the list of channels is not strictly the same for  all the files.<<BR>>__Different cleaning procedures__:  If you are cleaning artifacts from each acquisition run separately  using SSP or ICA projectors, you cannot share the channel file between  them (the projectors are saved in the channel file). ''' '''

   * '''Yes, use one channel file per subject''':<<BR>>This  is a common setting for EEG. The electrodes are in the same position  for all the files recorded on one subject, and the number of channels is  the same for all the files. To use this option, you should not be using  SSP/ICA projectors on the recordings, or they should be computed for  all the runs at once. ''' '''

   * '''Yes, use only one global channel file''':<<BR>>This  is never a recommended setting. It could be used in the case of an EEG  study where you use only standard EEG positions on a standard anatomy,  but only if you are not doing any advanced source reconstruction. If you  share the position of the electrodes between all the subjects, it will  also share the source models, which are dependent on the quality of the  recordings for each subject. This is complicated to understand at this  level, it will make more sense later in the tutorials. ''' '''

 1. In the context of this study, we are going to use the following settings:<<BR>>
  * '''No, use individual anatomy''': Because we have access to a T1 MRI scan of the subject.
  * '''No, use one channel file per condition/run''': The typical MEG setup.

 1. Click on '''[Create]'''.<<BR>><<BR>> {{attachment:createNewProtocol.gif}}

== Protocol exploration ==
The protocol is created and you can now see it in the database explorer. It is represented by the top-most node in the tree. ''' '''

 * You  can switch between '''Anatomy''' and  '''Functional data''' (sorted by subject, or sorted by conditions), with the three buttons  just above the database explorer. Read the tooltips of the buttons to  see which one does what. ''' '''
 * In the '''Anatomy''' view, there is a '''Default anatomy'''  node. It contains the ICBM152 anatomy, distributed by the Montreal  Neurological Institute (MNI), which is one of the template anatomy  folders that are distributed with Brainstorm. ''' '''
 * The '''Default anatomy'''  node contains the MRI and the surfaces that are used for the subjects  without an individual anatomy, or for registering multiple subjects to  the same anatomy for group analysis. ''' '''
 * There are no  subjects in the database yet, so both '''Functional data''' views are empty. ''' '''

 * Everything   you can do with an object in the database explorer (anatomy files,  subjects, protocol) is  accessible in its right-click menu. <<BR>><<BR>> ''' '''

 . {{attachment:treeNewProtocol.gif}}

== Set up a backup ==
Just  like any computer work, your Brainstorm database is always at risk.  Software bugs, computer or network crashes and manipulation errors can  cause the loss of months of data curation and computation. If the  database structure gets corrupted or if you delete or modify  accidentally some files, you might not be able to get your data back. '''__There is no undo button!__''' ''' '''

You  created your database, now take some time to find a way to make it  safe. If you are not familiar with backuping systems, watch some online  tutorials explaining how to set up an '''__automatic daily or weekly backup__ '''of your sensitive data. It might seem annoying and useless now, but could save you weeks in the future. ''' '''

== Changing the temporary folder ==
If  the amount of storage space you have for your user folder is limited  (less than 10Gb), you may have to change the temporary folder used by  Brainstorm. If you work on a centralized network where all the computers  are sharing the same resources, the system admins may impose limited  disk quotas to all users and encourage them to use local hard drives  instead of the limited and shared user folder. ''' '''

The  default temporary folder of Brainstorm is located in your user folder  (`$HOME/.brainstorm/tmp/`), so when you import recordings or calculate  large models, it may quickly fill up your limited quota and at some  point block your user account. To prevent this, select the menu '''File»Edit preferences'''  and set the temporary directory to a folder that is local to your  computer, in which you do not have any storage limitation. ''' '''

 . {{attachment:preferences.gif||width="500",height="375"}} ''' '''

== Summary ==
 * Different folders for: ''' '''
  * the '''program '''(`brainstorm3`). ''' '''
  * the '''database '''(`brainstorm_db`). ''' '''
  * the '''user directory''' (`.brainstorm`).
  * your '''original recordings.''' ''' '''
 * 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 interface. ''' '''
 * Do not try to maximize the main Brainstorm window: keep it small on one side of your screen. ''' '''

== Roadmap ==
The workflow described in these introduction tutorials include the following steps: ''' '''

 * Importing the anatomy of the subjects, the definition of the sensors and the recordings. ''' '''
 * Pre-processing, cleaning, epoching and averaging the EEG/MEG recordings. ''' '''
 * Estimating sources from the imported recordings. ''' '''
 * Computing measures from the brain signals of interest in sensor space or source space. ''' '''

{{attachment:workflow.gif}}

== Additional documentation ==
 * Forum: [[https://neuroimage.usc.edu/forums/showthread.php?1691|Moving the database to a different folder or drive]] ''' '''

<<HTML(<!-- END-PAGE -->)>> ''' '''

<<EmbedContent("https://neuroimage.usc.edu/bst/get_prevnext.php?prev=Tutorials&next=Testing2")>> ''' '''

<<EmbedContent(https://neuroimage.usc.edu/bst/get_feedback.php?Tutorials/CreateProtocol)>> ''' '''