|
Size: 21817
Comment:
|
← Revision 72 as of 2023-08-13 09:20:39 ⇥
Size: 22192
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 2: | Line 2: |
| ''Authors: Francois Tadel, Sylvain Baillet'' | ''Authors: Francois Tadel, Elizabeth Bock, Sylvain Baillet'' |
| Line 5: | Line 5: |
== 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. <<TAG(Advanced)>> 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. '''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 will 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''', don't think that a MEG-based tutorial is not adapted for you. Most of the practical aspects of the data manipulation is very similar in EEG and MEG. First start by reading 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 some 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]]. |
|
| Line 15: | Line 39: |
| * '''Windows''': My documents\brainstorm3 | * '''Windows''': Documents\brainstorm3 |
| Line 23: | Line 47: |
| * Managed automatically by the application: do not move, delete or add files by yourself. | * Managed by the application: do not move, delete or add files by yourself. |
| Line 25: | Line 49: |
| * '''Windows''': My documents\brainstorm_db | * '''Windows''': Documents\brainstorm_db |
| Line 31: | Line 55: |
| * Created automatically at Brainstorm startup. Typical location:<<BR>> * '''Windows''': C:\Documents and Settings\username\.brainstorm |
* Created at Brainstorm startup. Typical location:<<BR>> * '''Windows''': C:\Users\username\.brainstorm |
| Line 37: | Line 61: |
| * '''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. |
* '''defaults/''': Anatomy templates downloaded by Brainstorm. |
| Line 43: | Line 63: |
| * '''plugins/''': Plugins downloaded by Brainstorm (see tutorial [[Tutorials/Plugins|Plugins]]). * '''process/''': Personal process folder (see tutorial [[Tutorials/TutUserProcess|How to write your own process]]). * '''reports/''': Execution reports (see tutorial [[http://neuroimage.usc.edu/brainstorm/Tutorials/PipelineEditor#Report_viewer|Run processes]]). * '''tmp/''': Temporary folder, emptied every time Brainstorm is started with user confirmation.<<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 ([[https://neuroimage.usc.edu/brainstorm/Tutorials/CreateProtocol#Changing_the_temporary_folder|see below]]). {{{#!wiki tip Be sure that the paths to the '''Program''', '''Database''', and '''User''' directories do not contain special characters. [[https://neuroimage.usc.edu/forums/t/doesnt-work-brainstorm3-bat/40174|See related forum post]]. }}} |
|
| Line 50: | Line 77: |
| 1. If you haven't read in the installation instructions, do it now: [[Installation]]. 1. Start Matlab, go to brainstorm3 directory, and type "brainstorm" in Matlab command window.<<BR>> |
1. If you haven't read the installation instructions, do it now: [[Installation]]. 1. Start Brainstorm from Matlab or with the compiled executable.<<BR>> |
| Line 73: | Line 100: |
| The 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. 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. |
|
| Line 74: | Line 105: |
== The text is too small == If you have a high-resolution screen, the text and icons in the Brainstorm window may not scale properly, leading the interface to be impossible to use. Select the menu '''File > Edit preferences''', the slider at the bottom of the option window lets you increase the ratio of the Brainstorm interface. If it doesn't help, try changing the scaling options in your operating system preferences. {{attachment:preferences.gif}} |
|
| Line 83: | Line 119: |
| * Your Brainstorm database is a collection of protocols. | |
| Line 86: | Line 123: |
| * 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. |
* '''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. |
| Line 92: | Line 129: |
| * The current structure of the database does not allow to have more that one level of sub-folders for each subject. It is not possible to organize the files by session AND by condition.<<BR>><<BR>> {{attachment:db.gif}} | * The current structure of the database does not allow more than one level of sub-folders for each subject. It is not possible to organize the files by session AND by condition.<<BR>><<BR>> {{attachment:db.gif}} |
| Line 100: | Line 137: |
| * 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 correspondance. There is 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. * 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 (which may take some time). * 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 the folder to udpate > Reload. == Create first protocol == 1. Click on the File menu, and select, and select ''New protocol''.<<BR>><<BR>> {{attachment:menuFile.gif}} 1. Edit the protocol name and enter: "TutorialFirstSteps". It will automatically update the paths (''Anatomy path'' and ''Datasets path''). 1. ''Default properties for the subjects'': * These are the default settings that are used when creating new subjects. It is then possible to override those settings for each subject individually. * Our objective is to create one subject that uses the default anatomy Colin27, so select the option "''Yes, use protocol's default anatomy''". * The option ''Default channel file'' is a bit more complicated to understand. It defines at what level we want to define the sensors information (position, orientation, name...) in the database. To make you data management more efficient, you can in some cases use the same ''channel file'' for all the subjects, or for all the folders within one subject. For more information on this option, click on the '''Help button'''. * In this specific case, this option is not relevant because we are not going to import any recordings. 1. Once you get something like the following figure, click on ''Create''.<<BR>><<BR>> {{attachment:createNewProtocol.gif}} |
* 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. Menu File > New protocol.<<BR>><<BR>> {{attachment:menuFile.gif}} 1. Edit the protocol name and 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''': Default for all studies<<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''': Use with caution<<BR>>This can be a setting adapted to 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. However, to use this option, you should not be using SSP/ICA projectors on the recordings, or they should be computed for all the files at once. This may lead to some confusion and sometimes to manipulation errors. For this reason, we decided not to recommend this setting. * '''Yes, use only one global channel file''': Not recommended<<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}} |
| Line 122: | Line 167: |
| * You can switch between anatomy and functional data with the first three buttons in the toolbar. There are no subjects in the database yet, so the ''Functional data'' views are empty. However, in the ''Anatomy ''view, there is a ''(Default anatomy)'' node; it contains the MRI and the surfaces that can be used by default for the subjects without individual anatomy. * The default anatomy used in Brainstorm is based on the ''Colin27 ''MRI volume provided by the Montreal Neurological Institute (MNI): an average of 27 T1 scans of Colin Holmes brain ([[http://www.bic.mni.mcgill.ca/~louis/stx_history.html|more info]]). * The cortex surfaces here were extracted from this average MRI with FreeSurfer. * The inner and outer skull surfaces were generated with Brainstorm. * Display the ''Anatomy ''view, and click on the small "+" to expand the contents of the ''(Default anatomy)'' node. There is one MRI and several surfaces, identified by different icons. * Everything you can do with a node (anatomy files, subjects, protocol) is accessible by right-clicking on it. Take a few minutes to explore all the popup menus by yourself. Don't be afraid of clicking everywhere, at this point you cannot damage anything. |
* You can switch between anatomy and functional data 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 the ''Functional data'' views are empty. * Everything you can do with an object in the database explorer (anatomy files, subjects, protocol) is accessible by right-clicking on it. <<BR>><<BR>> |
| Line 135: | Line 175: |
== 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 == Some processes need to create temporary files on the hard drive. For example, when epoching MEG/EEG recordings, Brainstorm would first create a temporary folder "import_yymmdd_hhmmss", store all the epochs in it, then move them to the database when the epoching process is completed. The name of the temporary folder indicates its creation time (year/month/day_hour_minutes_seconds). At the end of the process, all the temporary files should be deleted automatically. The default folder where Brainstorm stores its temporary files is located in the user folder ('''$HOME/.brainstorm/tmp/'''), so before importing recordings or calculating large models, you have to make sure you have enough storage space available. 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. In such context, Brainstorm may quickly fill up your limited quota and at some point block your user account. 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. Select the menu '''File > Edit preferences''' and set the temporary directory to a folder that is local to your computer, in which you won't suffer from any storage limitation. If a process crashes or is killed before it deletes its temporary files, they would remain in the temporary folder until explicitly deleted. When starting Brainstorm, you would always get offered to delete the previous temporary files: always agree to it, unless they correspond to files generated by another session running simultaneously. Alternatively, you can delete these temporary files by clicking on the''' Empty''' button in the same preferences window. More information in the [[https://neuroimage.usc.edu/brainstorm/Tutorials/Scripting#Temporary_files|Scripting tutorial]]. {{attachment:preferences.gif}} |
|
| Line 138: | Line 196: |
| * the '''program '''(brainstorm3), * the '''database '''(brainstorm_db), * 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 == Fiducials selection (MRI Viewer) == A few more details about the MRI and the fiducials: Right-click on the MRI file > Edit MRI... . {{attachment:mriViewer.gif}} * Navigate in the volume by clicking anywhere in the slices, or by using the sliders below each image. * Once you have clicked on any orientation, you can use the '''mouse wheel''' to move to the next/previous slice in the same orientation. * '''Zoom '''in and out with the magnifying glass buttons at the bottom of the figure * There are three small buttons above each image. They may be useful when you import your own MR volumes, if they are not oriented in the way Brainstorm wants them (e.g. you see the ''Sagittal ''title on top of the coronal view; or the small white "''P''", which is supposed to indicate the posterior part of the head, points the nose). Leave your mouse a few seconds over any button to read its description tooltip. Click on them and try to understand what they are doing. * Image contrast can be changed with the mouse: click and hold the right button on one image, and move your mouse up and down (this operation will be later referred as ''right-click+move''). * Right-clicking in any view shows a popup menu that will be described in the following tutorials. * You can define six points on the MRI: * Three to define the Subject Coordinate System (SCS):<<BR>>Nasion (NAS), Left pre-auricular point (LPA), Right pre-auricular point (RPA) * Three to define the Normalized coordinate system (NCS):<<BR>>Anterior commissure (AC), Posterior commissure (PC), and any Interhemispheric point (IH) * More information on how to define the fiducial points on the CoordinateSystems page. * To define a point, position the three views at the point your want to define (pointed by the 3 crosses), and click on the ''Set ''button. Later you can click on ''View ''to move the views to this point again. * You can see that all the points are already defined on this MRI, but you should always check their positions. For many reasons, each research group has a different way to define those points. So you may not position the ears or the nasion exactly the same way as we do. Do not hesitate to move the fiducials to better fit your needs. * The ''Display options'' panel allows to hide some of the components. If the ''MIP/Anatomy ''checkbox is selected, the Maximum Intensity Power is displayed instead of the regular slices: At each point, the value displayed is the maximum value across all the slices. * The ''Coordinates ''panel shows the (x,y,z) coordinates in the coordinate systems managed by Brainstorm: MRI and SCS. * Once you're done, click on ''Cancel ''(unless you really want to save all your experiments). == MRI visualization == There are many different ways to display the MR volumes. Right click on the ''T1-MRI'' in ''Default anatomy'', menu ''Display''. Just click everywhere and try all the options by yourself, it is the best way to learn.<<BR>><<BR>> {{attachment:popupMri.gif}} ==== MRI Viewer ==== Already introduced in this tutorial<<BR>>It is the default visualization mode; when you double-click on the MRI file, it brings up the MRI Viewer. ==== Axial / coronal / sagittal slices ==== {{attachment:mriSlicesContact.gif||height="231",width="210"}} * '''Zoom''': mouse wheel (or two finger-move on a MacBook pad) * '''Move '''in zoomed image: click + move * '''Adjust contrast''': right click + move up/down * Colormap selection in menu * Save as image in menu ==== 3D orthogonal slices ==== ||<tablewidth="200px"> {{attachment:mriSlices3d.gif||height="229",width="292"}} || {{attachment:menuShortcut.gif}} || * Simple mouse operations * '''Rotate''': click + move * '''Zoom''': mouse wheel (two finger-move on a MacBook pad) * '''Move object''': left+right click + move * '''Move MRI slices''': right click + move along direction of the slice<<BR>>(or use the ''Resect ''panel in the ''Surface ''tab) * '''Colormap contrast/brightness''': click on the colorbar, and move up/down (brightness) or left/right (contrast) * '''Reset view''': double click * '''Reset colormap''': double-click on the colorbar * Popup operations (right-click on the figure) * '''Colormap''': Full ''Anatomy ''colormap edition (detailed in next tutorial) * '''MRI Display''': For now, contains only the MIP option (Maximum Intensity Power). If checked, for each orientation: displays the maximum along all the slices instead of the proper slice. * '''Get coordinates''': Pick a point in any 3D view and get its coordinates * '''Snapshots''': save images or movies from this figure * '''Figure''': change background color, display axes and menus for an advanced figure editing and management using Matlab tools. * '''Views''': configure camera position with predefined settings. * Keyboard shortcuts: * Notice the indications in the right part of the popup menu (''CTRL+A'' in front of ''Figures>Axes'', ''"1"'' in front of ''Views>Left''), they represent the keyboard shortcut for each menu. * '''Views shortcuts (0,1,2...9 and "=")''': Remember them, they will be very useful when exploring the cortical sources. It is much faster to press a key to switch from left to right hemisphere, than having to rotate the brain with the mouse. * Surfaces tab (in the Brainstorm main window): * This panel is primarily dedicated to the surfaces display, but some controls can also be useful for the 3D MRI view. * ''Transparency ''slider * ''Smooth ''slider: it changes the threshold applied to the MRI slices. If you set it zero, you will see the full slices, as extracted from the volume. * ''Resect ''panel: you can change the position of the slices with the three sliders. == Surfaces visualization == There is only one way to display the surfaces: in 3D figures. To display a surface you can either double-click on it or right-click > Display. * The mouse and keyboard operations are the same described for the 3D MRI display also apply here. * If you display two surfaces from the same subject, they will be displayed on the same figure. * Surfaces tab: more options are available<<BR>><<BR>> {{attachment:panelSurfaces.gif}} * Open the ''Cortex ''surface and try all the buttons and sliders. Then do the same with the ''Scalp ''surface (''Head''). All the controls should have some effect on the display, except the sliders in the "''Data options''" panel. They are useful only when some additional data is mapped on the surfaces. * Multiple surfaces: If you have more than one surface in a figure, you need to select the surface you want to edit before changing its properties. The list of the available surfaces is displayed on top of the ''Surfaces ''tab. * You can also quickly add or remove surfaces in any 3D figure with the top-right buttons of the ''Surfaces ''tab. == Coordinates tab == * Close all the figures. Open the cortex surface again. * Right-click on the 3D figure, select "Get coordinates". A new window appears. * Click anywhere on the cortex surface: a big yellow cross appears, and the coordinates of the point are displayed in all the available coordinates systems (see page: CoordinateSystems) * MRI: MR volume, in millimeters (multiplied with the Voxsize field in the MRI file). * SCS: Subject Coordinates System, in millimeters * MNI: Montreal Neurological Institute standard coordinates * You can click on "View / MRI" to see where this point is located in the MRI, using the MRI Viewer. <<BR>><<BR>> {{attachment:panelCoord.gif}} {{attachment:panelCoordPt.gif}} == Create a subject == If you explored well, you should have found the "''New subject''" menu in the protocol's popup menu. ||<tablewidth="200px"#ffffff style="vertical-align:top; "> {{attachment:menuNewSubject.gif}} || {{attachment:createNewSubject.gif}} || * Usually, the only thing you need to do here is to edit the name of the subject. * But you can also override here the protocol's defaults regarding the sharing of anatomy and channel file between subjects and conditions. For the example, leave selected the "''Yes, use default anatomy''" option. Then click on ''Save''. * You should see a the new subject in both ''Anatomy ''and ''Functional data'' views. * In the Anatomy view, the subject node only contains a link called (Default anatomy). It is here just to remind that the subject is using the default ''MNI Colin27'' anatomy.<<BR>><<BR>> {{attachment:subjectDefaultAnat.gif}} == Change the default anatomy == When you create a new protocol, the program makes a copy of the Colin27 anatomy and sets it as the default for the protocol. It means that you will be able to use the Colin27 brain as a substitute for the subjects without an individual MRI, or as the common brain for group analysis. Other sets of MRI+surfaces are available to replace the Colin27 anatomy. Right-click on ''(Default anatomy)'' > Use template. If a package is not currently available on your system, it will be downloaded from the Brainstorm website and saved in $HOME/.brainstorm/templates. The available options are: * '''Colin27''': Average of 27 scans of the same head, processed with FreeSurfer 5.3: [[http://www.bic.mni.mcgill.ca/ServicesAtlases/Colin27|more information]] * '''Colin27_2012''': Previous version of the default anatomy distributed with Brainstorm * '''ICBM152''': Non-linear average of 152 subjects, processed with FreeSurfer 5.3: [[http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin2009|more information]] * '''FSAverage''': Average of 40 subjects using a spherical averaging described in [[http://nmr.mgh.harvard.edu/~fischl/reprints/morphing_human_brain_mapping_reprint.pdf|(Fischl et al. 1999)]].<<BR>>It is the default FreeSurfer brain: please [[https://surfer.nmr.mgh.harvard.edu/registration.html|register here]] if you are using it. * '''Infant7w''': 7-week infant brain with the antomical atlas presented in [[http://www.sciencedirect.com/science/article/pii/S105381191400411X|(Kabdebon et al. 2014)]]. They all include the following information: * T1 MRI volume * Cortex surface: high-resolution (~300.000 vertices) and low-resolution (15.000 vertices) * Head surface: based on the head used for FSAverage in the MNE software * FreeSurfer spherical registration of each hemisphere, with which we can co-register the individual brains processed with FreeSurfer with the selected default anatomy * FreeSurfer surface-based atlases: Desikan-Killiany, Destrieux, Brodman, Mindboggle<<BR>>(plus Yeo2011 and PALS for FSAverage only) The atlases will be discussed in the following tutorials. For more information on the interactions between FreeSurfer and Brainstorm: [[Tutorials/LabelFreeSurfer|read this tutorial]]. {{attachment:changeDefault.gif|changeDefault1.gif}} If you click on any of the download options, it downloads it into your $HOME/.brainstorm/templates folder: {{attachment:changeDefault2.gif}} Then the list of files in the (default anatomy) folder is replaced with the new template. {{attachment:changeDefault3.gif}} == Modify the default MRI fiducials == The fiducial points (Nasion, LPA, RPA) used in your recordings might not be the same as the ones used in the anatomy templates in Brainstorm (Colin27, ICBM152, FSAverage). By default, the LPA/RPA points are defined at the junction between the tragus and the helix, as represented with the red dot in the [[http://neuroimage.usc.edu/brainstorm/CoordinateSystems|Coordinates systems page]]. If you want to use an anatomy template but you are using a different convention when digitizing the position of those points, you have to modify the default positions of the template with the MRI Viewer. * Go to the anatomy view * In (default anatomy), right-click on the MRI > Edit MRI * Modify the position of the fiducial points to match your own convention * Click on [Save], it will update the surfaces to match the new coordinate system == Next == Now you know how to create a protocol with a default anatomy, and visualize MR volumes and surfaces. Next step: how to [[Tutorials/TutImportAnatomy|import an individual anatomy]] for a subject. <<EmbedContent("http://neuroimage.usc.edu/bst/get_prevnext.php?prev=Tutorials&next=Tutorials/TutFirstSteps")>> <<EmbedContent(http://neuroimage.usc.edu/bst/get_feedback.php?Tutorials/CreateProtocol)>> |
* the '''program '''(brainstorm3). * the '''database '''(brainstorm_db). * 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 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}} <<TAG(Advanced)>> == Moving a database == If you are running out of disk space or need to share your database with someone else, you may need to copy or move your protocols to a different folder or drive. Each protocol is handled independently by Brainstorm, therefore in order to move the entire database folder (brainstorm_db), you need to repeat the operations below for each protocol in your database. ==== Copy the raw files ==== The original continuous files are not saved in the Brainstorm database. The "Link to raw files" depend on a static path on your local computer and cannot be moved easily to a new computer. You can copy them inside the database before moving the database to a different computer/hard drive using the menu: File > Export protocol > '''Copy raw files to database'''. This will make local copies in .bst format of all your original files. The resulting protocol would be larger but portable. This can also be done file by file: right-click > File > '''Copy to database'''. ==== Export a protocol ==== The easiest option to share a protocol with a collaborator is to export it as a zip file. * '''Export''': Use the menu File > Export protocol > '''Export as zip file'''.<<BR>>Avoid using spaces and special characters in the zip file name. * '''Import''': Use the menu File > Load protocol > '''Load from zip file'''. <<BR>>The name of the protocol created in the brainstorm_db folder is the name of the zip file. If there is already a protocol with this label, Brainstorm would return an error. To import the protocol as a different name, you only need to rename the zip file before importing it. * '''Size limitation''': This solution is limited to smaller databases: creating zip files larger than a few Gb can take a lot of time or even crash. For larger databases, prefer the other options below. ==== Export a subject ==== Similar as the protocol export, but extracts only the files needed by a single subject. * '''Export''': Right-click on the subject > File > '''Export subject'''. * '''Import as new protocol''': Use the menu File > Load protocol > '''Load from zip file'''. * '''Import in an existing protocol''': Use the menu File > Load protocol > '''Import subject from zip'''. ==== Move a protocol ==== To move a protocol to a different location: 1. [Optional] Set up a backup of your entire brainstorm_db folder if your haven't done it yet. There will be no undo button to press if something bad happens. 1. [Optional] Copy the raw files to the database (see above) 1. '''Unload''': Menu File > Delete protocol > '''Only detach from database'''. 1. '''Move''': Move the entire protocol folder to a different location. Remember a protocol folder should be located in the "brainstorm_db" folder and should contain only two subfolders "data" and "anat". Never move or copy a single subject manually. 1. '''Load''': Menu File > Load protocol > '''Load from folder''' > Select the new location of the protocol 1. If you want to move the entire "brainstorm_db" folder at once, make sure you detach all the protocols in your Brainstorm installation first. ==== Duplicate a protocol ==== To duplicate a protocol in the same computer: * '''Copy''': Make a full copy of the protocol to duplicate in the brainstorm_db folder, e.g. TutorialIntroduction => TutorialIntroduction_copy. Avoid using any space or special character in the new folder name. * '''Load''': Menu File > Load protocol > '''Load from folder''' > Select the new protocol folder <<HTML(<!-- END-PAGE -->)>> <<EmbedContent("https://neuroimage.usc.edu/bst/get_prevnext.php?prev=Tutorials&next=Tutorials/ImportAnatomy")>> <<EmbedContent(https://neuroimage.usc.edu/bst/get_feedback.php?Tutorials/CreateProtocol)>> |
Tutorial 1: Create a new protocol
Authors: Francois Tadel, Elizabeth Bock, Sylvain Baillet
Contents
- How to read these tutorials
- Presentation of the experiment
- Brainstorm folders
- Starting Brainstorm for the first time
- Main interface window
- The text is too small
- Database structure
- Database files
- Create your first protocol
- Protocol exploration
- Set up a backup
- Changing the temporary folder
- Summary
- Roadmap
- Moving a database
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.
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.
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 will 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, don't think that a MEG-based tutorial is not adapted for you. Most of the practical aspects of the data manipulation is very similar in EEG and MEG. First start by reading these introduction tutorials using the MEG example dataset provided, then when you are familiar with the software, go through the tutorial "EEG and Epilepsy" to get some 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: 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.
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: Documents\brainstorm3
Linux: /home/username/brainstorm3
MacOS: Documents/brainstorm3
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: Documents\brainstorm_db
Linux: /home/username/brainstorm_db
MacOS: Documents/brainstorm_db
3. User directory: ".brainstorm"
Created at Brainstorm startup. Typical location:
Windows: C:\Users\username\.brainstorm
Linux: /home/username/.brainstorm
MacOS: /Users/username/.brainstorm
- Contains:
brainstorm.mat: Brainstorm user preferences.
defaults/: Anatomy templates downloaded by Brainstorm.
mex/: Some mex files that have to be recompiled.
plugins/: Plugins downloaded by Brainstorm (see tutorial Plugins).
process/: Personal process folder (see tutorial How to write your own process).
reports/: Execution reports (see tutorial Run processes).
tmp/: Temporary folder, emptied every time Brainstorm is started with user confirmation.
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 (see below).
Be sure that the paths to the Program, Database, and User directories do not contain special characters. See related forum post.
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.
Starting Brainstorm for the first time
If you haven't read the installation instructions, do it now: Installation.
Start Brainstorm from Matlab or with the compiled executable.
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> =================================
- Read and accept the license file.
- Select your Brainstorm database directory (brainstorm_db).
If you do something wrong and don't 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 the software preferences (menu File > Edit preferences).
Main interface window
The 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.
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.
The text is too small
If you have a high-resolution screen, the text and icons in the Brainstorm window may not scale properly, leading the interface to be impossible to use. Select the menu File > Edit preferences, the slider at the bottom of the option window lets you increase the ratio of the Brainstorm interface. If it doesn't help, try changing the scaling options in your operating system preferences.
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.
- 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.
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 more than one level of sub-folders for each subject. It is not possible to organize the files by session AND by condition.
Database files
- The database folder "brainstorm_db" is managed completely from the graphic user interface (GUI).
- All the files in the database have 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: brainstorm_db/protocol_name/anat/subject_name
Functional data: 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
Menu File > New protocol.
Edit the protocol name and enter: "TutorialIntroduction".
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.- 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:
Select when you have individual MRI scans for all the participants of your study.Yes, use default anatomy:
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: Default for all studies
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.
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.
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: Use with caution
This can be a setting adapted to 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. However, to use this option, you should not be using SSP/ICA projectors on the recordings, or they should be computed for all the files at once. This may lead to some confusion and sometimes to manipulation errors. For this reason, we decided not to recommend this setting.Yes, use only one global channel file: Not recommended
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.
In the context of this study, we are going to use the following settings:
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.
Click on [Create].
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 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 the Functional data views are empty.
Everything you can do with an object in the database explorer (anatomy files, subjects, protocol) is accessible by right-clicking on it.
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
Some processes need to create temporary files on the hard drive. For example, when epoching MEG/EEG recordings, Brainstorm would first create a temporary folder "import_yymmdd_hhmmss", store all the epochs in it, then move them to the database when the epoching process is completed. The name of the temporary folder indicates its creation time (year/month/day_hour_minutes_seconds). At the end of the process, all the temporary files should be deleted automatically.
The default folder where Brainstorm stores its temporary files is located in the user folder ($HOME/.brainstorm/tmp/), so before importing recordings or calculating large models, you have to make sure you have enough storage space available.
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. In such context, Brainstorm may quickly fill up your limited quota and at some point block your user account.
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. Select the menu File > Edit preferences and set the temporary directory to a folder that is local to your computer, in which you won't suffer from any storage limitation.
If a process crashes or is killed before it deletes its temporary files, they would remain in the temporary folder until explicitly deleted. When starting Brainstorm, you would always get offered to delete the previous temporary files: always agree to it, unless they correspond to files generated by another session running simultaneously. Alternatively, you can delete these temporary files by clicking on the Empty button in the same preferences window. More information in the Scripting tutorial.
Summary
- Different folders for:
the program (brainstorm3).
the database (brainstorm_db).
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 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.
Moving a database
If you are running out of disk space or need to share your database with someone else, you may need to copy or move your protocols to a different folder or drive. Each protocol is handled independently by Brainstorm, therefore in order to move the entire database folder (brainstorm_db), you need to repeat the operations below for each protocol in your database.
Copy the raw files
The original continuous files are not saved in the Brainstorm database. The "Link to raw files" depend on a static path on your local computer and cannot be moved easily to a new computer. You can copy them inside the database before moving the database to a different computer/hard drive using the menu: File > Export protocol > Copy raw files to database. This will make local copies in .bst format of all your original files. The resulting protocol would be larger but portable. This can also be done file by file: right-click > File > Copy to database.
Export a protocol
The easiest option to share a protocol with a collaborator is to export it as a zip file.
Export: Use the menu File > Export protocol > Export as zip file.
Avoid using spaces and special characters in the zip file name.Import: Use the menu File > Load protocol > Load from zip file.
The name of the protocol created in the brainstorm_db folder is the name of the zip file. If there is already a protocol with this label, Brainstorm would return an error. To import the protocol as a different name, you only need to rename the zip file before importing it.Size limitation: This solution is limited to smaller databases: creating zip files larger than a few Gb can take a lot of time or even crash. For larger databases, prefer the other options below.
Export a subject
Similar as the protocol export, but extracts only the files needed by a single subject.
Export: Right-click on the subject > File > Export subject.
Import as new protocol: Use the menu File > Load protocol > Load from zip file.
Import in an existing protocol: Use the menu File > Load protocol > Import subject from zip.
Move a protocol
To move a protocol to a different location:
- [Optional] Set up a backup of your entire brainstorm_db folder if your haven't done it yet. There will be no undo button to press if something bad happens.
- [Optional] Copy the raw files to the database (see above)
Unload: Menu File > Delete protocol > Only detach from database.
Move: Move the entire protocol folder to a different location. Remember a protocol folder should be located in the "brainstorm_db" folder and should contain only two subfolders "data" and "anat". Never move or copy a single subject manually.
Load: Menu File > Load protocol > Load from folder > Select the new location of the protocol
- If you want to move the entire "brainstorm_db" folder at once, make sure you detach all the protocols in your Brainstorm installation first.
Duplicate a protocol
To duplicate a protocol in the same computer:
Copy: Make a full copy of the protocol to duplicate in the brainstorm_db folder, e.g. TutorialIntroduction => TutorialIntroduction_copy. Avoid using any space or special character in the new folder name.
Load: Menu File > Load protocol > Load from folder > Select the new protocol folder