Turbo-BrainVoyager
User's Guide
Turbo-BrainVoyager (TBV) is a highly optimized software package for real-time analysis and
advanced visualization of functional and structural magnetic resonance imaging data sets.
Turbo-BrainVoyager allows quality assurance of ongoing fMRI measurements by assessing had
motion and by incrementally computing statistical maps as contrasts of a General Linear Model
(GLM). Statistical information can be visualized on original slices (multi-slice view as well as in
orthographic 3D mode using anatomical scans of the subject. If anatomical data sets of the
subject are prepared with BrainVoyager QX prior to the real-time functional measurement,
statistical information can be viewed in Talairach space as well as on surface (mesh)
representations. TBV allows to select regions-of-interest (ROIs) from any brain view and plots
time courses, estimated beta values and event-related averages dynamically. TBV also allows to
use machine learning tools to classify and predict distributed patterns of activity ("brain
reading"). Due to its computational and visualization capabilities, TBV supports advanced realtime applications such as neurofeedback, brain computer interfaces (BCIs), adaptive
experimental designs and neurosurgical monitoring.
Turbo-BrainVoyager is based on the BrainVoyager QX software package with the following new
or modified features:
New routines for full-fledged incremental statistical data analysis (recursive least
squares GLM) of block- and event-related designs.
Optimized routines for multi-voxel pattern classification (MVPC) using support vector
machines (SVMs).
Incremental preprocessing routines including 3D motion correction, 3D spatial
smoothing and drift correction based on confound predictors; additional steps such as
slice scan time correction can be performed at the end of a run.
Easy to use graphical user interface (GUI) with only essential elements.
Design matrices, contrasts and other relevant statistical data are created automatically
from a defined protocol.
Instead of a complete protocol, real-time protocols may be used to build up the design
matrix on the fly during scanning.
Interactive GUI allowing exploring incoming data while running the actual
measurement, including specification of multiple contrasts as well as conjunction of
contrasts.
Advanced volume and surface visualizations with fast statistical updates ("movie") by
keeping transformation matrices to calculated statistical data in original image space.
Incorporation of Volumes-Of-Interests (VOIs) in Talairach space to (re-)load ROIs.
Specification of ROIs at any time with plots of time courses, event-related averages
and dynamically estimated beta values.
Integrated neurofeedback module to display data to subject and to save ROI data
incrementally for use with custom programs.
Storage of fMRI raw data on local hard drive in BrainVoyager format after functional
run has been completed allowing an easy transition to in-depth data analysis with
BrainVoyager QX or other fMRI software packages.
Support for custom processing and export of ROIs and full signal and statistical data
via a powerful plugin interface.
Support for real-time ICA analysis implemented as a plugin using the plugin map
visualization functions.
Previously recorded runs can also be reloaded and inspected at any time. Turbo-BrainVoyager is
optimized for real-time analysis and is not a replacement for BrainVoyager QX or other offline
software. There are, for example, no routines for head and cortex segmentation, Talairach
transformation and statistical group analyses. Some of the advanced visualization features
require anatomical processing (e.g. Talairach transformation, surface mesh creation) in
BrainVoyager QX prior to real-time analysis in TBV. Turbo-BrainVoyager 3.0 runs on Microsoft
Windows XP/Vista/7, Linux (2.6 kernel), and Mac OS X 10.5/10.6.
The next section provides an overview of TBV's operation followed by in-depth descriptions of its
features. If you are new to Turbo-BrainVoyager, you may also want to run the provided sample
data sets. It is also recommended to have a look at the release notes.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
Release Notes
Version 3.0
Turbo-BrainVoyager 3.0 adds the following new features and enhancements:
Open Architecture via Plugin Interface. The new plugin interface allows full access
to all relevant internal data structures supporting any kind of custom processing. In
order to quickly learn how to write plugins, the source code of two plugins are
provided as examples; the compiled executable of these plugins can also directly be
used by selecting them in the Plugins menu. Another includede plugin implements realtime ICA (see below) that uses advanced API functions allowing to visualize custom
maps in real-time.
The plugin "Example Plugin - ROI Processing" demonstrates how one may access the
content of all currently defined ROIs, both at the level of mean signal values as well as
at the voxel level. This feature allows, for example, to combine signal time courses
such as subtracting the values of a "background ROI" from the values in functionally
specific regions; the result of such processing can be exported for custom real-time
visualization software.
The plugin "Example Plugin - Export Volume Data" demonstrates how at each
incremental time point preprocessed raw data, beta maps and t maps can be accessed
enabling any kind of custom real-time processing as well as export of the full data to
external software such as Matlab, e.g. to perform additional calculations or to create
custom (feedback) displays.
Real-Time Multi-Voxel Pattern Classification. This version introduces real-time
multi-voxel pattern classification based on support vector machines (SVMs). In a
training phase, data from one or more runs can be specified. At any moment in a test
run, incremental classification can be turned on to predict the class of evoked activity.
This allows to conduct online "brain reading" applications.
Real-time Independent Component Analysis (rt-ICA). Real-time ICA is now
available as a plugin that has been implemented by Fabrizio Esposito (Brain
Innovation). When launching it from the Plugins menu, it will ask for a range of slices
and a temporal window that will be used for the data-driven multivariate detection of
functional networks. If a region-of-interest has been defined, the discovered networks
(components) will be ranked with respect to the overlap of the components with the
ROI, i.e. the component(s) are visualized that include the selected region. Using the
Show plugin maps option, it is possible to show either the calculated plugin maps
(components) or the standard GLM-based contrast maps.
Support for GE Signa HDxt Scanners. The recent generation of GE scanners exports
DICOM data incrementally that can now be processed by Turbo-BrainVoyager.
Advanced 3D Visualization for Philips Data. It is now also possible for exported
Philips (DRIN) data to visualize real-time maps in intra-session and extra-session
(ACPC, TAL space) 3D anatomical data sets. The new alignment options also allow
using defined VOIs across scanning sessions. In the current release this feature
requires the use of BrainVoyager QX.
Improved Support for Mesh Visualization. Beyond folded surfaces supported
previously, It is now possible to visualize incrementally analyzed data on inflated and
flattened cortex meshes; the inflated mesh(es) need to be specified in the VMR-SRF
tab of the TBV Settings dialog; note that the folded meshes that were used to create
the inflated/flattened meshes need to be stored in the same folder since the morphed
mesh look up the coordinates of vertices in the folded version to perform correct
visualization.
Version 2.8
Besides bug fixes, Turbo-BrainVoyager 2.8 adds the following enhancements:
Improved Support for Siemens real-time export. The new Siemens export function
introduced with scanner software VB15A is now better supported and documented.
Delayed feedback. The "Neurofeedback" dialog now allows to provide not only direct
(ongoing) feedback but also feedback at the end of blocks. Such "delayed feedback" of
the mean level of activity of a whole block may be helpful in the context of some
clinical neurofeedback applications. This option can be turned on by enabling the
"Delayed feedback" option in the "Feedback type" field of the "Neurofeedback" dialog.
Click the "Options" button to invoke the "Delayed Feedback Settings" dialog that can be
used to select the protocol condition that should be used for calculating delayed
feedback values. You may also specify the data points used for calculating the baseline
value ("Baseline interval") as well as the time points used to calculate the average
activation value with respect to the baseline ("Modulation interval"). You may also
specify a "Feedback file" that will contain the stored feedback values that can be used
for providing feedback to the subject using custom software. The "Update feedback
file" value specifies when the feedback file should be written (value must be larger
than end point of modulation interval) and the "Scale beta value" spin box can be used
to specify a value for scaling the estimated percent signal change beta values.
Improved feedback output for custom applications. In previous versions, volumeby-volume files containing mean ROI signal values (.RTP) files was only produced
when the "Neurofeedback" dialog was open and when the time course feedback option
was selected. The .RTP files are especially useful for custom processing of real-time
ROI data. In this version, the "Log ROI Time Point Files (RTPs)" output option can now
be turned on/off from the "Analysis" menu, i.e. opening the "Neurofeedback" dialog is
no longer necessary. This option is turned on as default. Furthermore, the mean ROI
signal values are now stored as float values for highest precision (also in ".ERT" files
that also store data of individual voxels).
Version 2.6
Turbo-BrainVoyager 2.6 adds the following enhancements:
Support for new Siemens real-time export. With recent software releases, Siemens
supports a new real-time export functionality saving each volume of data in a mosaic
Dicom file. This feature must be turned on requiring an IDEA license. For details,
consult the Siemens documentation. Turbo-BrainVoyager 2.6 is able to use the
exported data. This requires specification of the "SIEMENS_DICOM_MOSAIC" data type
and a specification of the first file, e.g. as "001_000003_000001.dcm" (if this is the
scan (series) 3). Subsequent files would be written as "001_000003_000002.dcm",
"001_000003_000003.dcm" and so on.
Conjunction contrasts. A new option is now available allowing to visualize a map as
the conjunction of all currently selected contrasts.
Compatibility with BrainVoyager QX. This version increases the compatibility of the
produced output files with BrainVoyager QX. The order of slices is no longer reversed
in TBVas in previous versions, which is visible in the multi slice view but not in the
volume views since for visualization the order of slices is adjusted in such a way that
the brain appears upright in the respective views. The increased compatibility with
BrainVoyager QX allows to load and further process TBV data.
Version 2.4
Besides improvements and bug fixes, Turbo-BrainVoyager 2.4 adds the following new features:
Smoothed Feedback. The bar graph display in the Neurofeedback dialog may now
show a smoothed version of the calculated feedback signal.The Avergage feedback
values field allows to specify how many recent values are averaged to obtain the
current display value. With the default value of "1", no averaging takes place; while
this gives feedback about momentary changes of the ROI BOLD data, the feedback
signal might fluctuate substantially. A large value (e.g. "10" or more) results in a very
smooth feedback signal but at the cost of a long delay with respect to the underlying
cognitive events. As a good compromise, we suggest values between "3" and "5"
implementing a modest temporal low-pass filter.
Dynamic ROIs. It is now possible to automatically optimize ROIs by specifying that a
percentage of "top" voxels should be determined and used as the efffective sub-ROI.
Dynamic ROIs generally lead to better signal extraction from ROIs, especially in case
of coarse anatomical ROI specification. But also functional ROIs benefit from dynamic
selection: By defining rather broad initial ROIs, dynamic voxel selection ensures that
the best sub-ROI will be determined even if there are small alignment errors across
successive runs or movement-related slice shifts. Dynamic ROIs can be turned on from
the Neurofeedback dialog, for details check the Dynamic ROIs documentation.
Incremental ROI Beta Export. For neurofeedback studies, the Neurofeedback dialog
can be used to create basic feedback displays, which can be presented to subjects,
e.g. by using the "Feedback Presenter" software. To support creation of special
feedback displays for custom software, Turbo-BrainVoyager exports "extended ROI
time course" (.ERT) files if the Log ROI Time Courses option is enabled in the Analysis
menu. In this file, the signal values of each ROI (and even for each voxel within ROIs)
are stored incrementally to disk: When the data for a time point is processed, ROI
signal values are appended to the experiment's .ERT file. For several purposes, it
might be desirable to know the estimated beta values for each ROI. While custom
software could use the exported ROI time course values to calculate beta values, this
version of Turbo-BrainVoyager adds the Log ROI Betas option in the Analysis menu,
which is enabled as default. With this option turned on, the estimated condition beta
values are incrementally saved in a "beta time course" (.BTC) file.
Preloading VOI Files. ROIs defined in "native" space (.ROI files) can be loaded at any
time. A useful option is that a .ROI file can be specified already before a prepared
.TBV file is executed, i.e. before any data has been processed. This is useful during a
neurofeedback session when ROIs have been determined in a localizer run, which
should be used in subsequent neurofeedback runs. ROIs can be also defined in ACPC or
Talairach space when using 3D data sets. In this case the ROIs are stored in .VOI files
either from Turbo-BrainVoyager or from BrainVoyager QX. While .VOI files could be
loaded already in previous versions, this release of TBV allows to preload a VOI file in
a similar way as described above for .ROI files.
Version 2.2
Strings for directories (e.g. watch folder, target folder, but also references to files
such as protocols) can now be specified in a relative manner with respect to the folder
containing the TBV file. A relative path begins with a "./" substring. When reading a
TBV settings file, relative paths are expanded by prepending the path containing the
TBV file. When saving a TBV file, paths are made relative if they reside within the
folder with the TBV file or in any subfolder. This new mechanism allows it to move
data to new places without breaking folder and file location specifications.
The TBV Settings dialog now shows the value of the TimeOutSeconds value. This value
had to be changed directly in the ".tbv" file in previous versions but can now be
changed in the General tab of the TBV Settings dialog.
Philips provides a elegant interface to export data during real-time scanning with the
new DRIN system that is now supported in Turbo-BrainVoyager.
When working with ROIs/VOIs, it was not possible to switch between multiple ROIs
since all newly opened ROI (interactively or by loading a file) were always added to
the already existing ones. The Analysis menu now has an entry Remove ROI Time
Courses deleting all currently available ROI time courses. New time courses can be
then added interactively or by loading ROI / VOI files from disk.
The code routines for statistical and visualization routines has been further optimized
with an overall gain of 50-100% processing time.
The Neurofeedback dialog has been improved calculating more sensitive baseline
values and also allows to present feedback for 2 ROIs with 2 thermometer displays.
For more information, please contact goebel_at_brainvoyager_dot_com.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
Overview
Performing real-time analysis with Turbo-BrainVoyager requires availability of a TBV settings
file containing information about the upcoming functional measurement. If a proper TBV settings
file is available, real-time analysis can be started by clicking the red Record button. In order to
learn how to use Turbo-BrainVoyager, it is recommended to run the provided example data
sets.
A TBV settings file can be easily created and modified using the TBV Settings dialog. Once a
settings file has been created matching a particular environment (e.g. data format), only small
adjustments are typically necessary to create TBV settings files for additional experiments. To
select a settings file use the Set New TBV File item in the File menu. When launching TurboBrainVoyager the next time, it automatically loads the last used settings file. This allows to
inspect and re-analyze the data of the last experiment by clicking the Reload Data button (if the
data has not been removed). In case that the next functional run uses the same settings as the
previous one, real-time analysis may be simply started by clicking the Record main button. In
most cases, however, at least the folder containing the new data and a specific experimental
protocol needs to be selected first using the TBV Settings dialog.
As soon as data becomes available from the scanner, TBV reads it volume-by-volume from a
folder, called WatchFolder in the TBV settings file. A few volumes may be discarded according to
the NrOfSkippedVolumes entry in the settings file to avoid the T1 saturation effects (high
intensity values). If specified, 3D motion correction is performed aligning each (but the first)
volume to a reference volume, which is the first volume scanned (and potentially discarded).
The detected 6 motion parameters are plotted in a time course window. Each motion corrected
volume may be spatially smoothed to increase signal to noise. Incoming volumes (time points)
are incrementally statistically analyzed using a General Linear Model (recursive least squares
GLM) based on an automatically created design matrix using the provided stimulation protocol.
Hypothesis testing is performed using contrasts, which are typically also automatically created.
Alternatively, a ContrastFile may be specified in the TBV settings file containing any desired
contrast definitions. Available contrasts are shown in the contrast list of the main window and
may be turned on and off for display at any time. Up to 4 contrasts may be displayed
simultaneously (out of arbitrary many contrasts), each with its own color or with a generic lookup table. Additional confound predictors may be added for removal of linear trends and lowfrequency drifts. The incrementally calculated contrast t maps are thresholded with a value
specified in the settings file and displayed on the original slices (multi-slice view) as well as
more advanced visualizations. The statistical threshold can also be adjusted on the fly during
analysis. To suppress isolated voxels, an in-plane cluster-size threshold may be specified.
Various visualizations of the brain are available. The default visualization is a multi-slice view
providing a good overview of the updated statistical information on top of the original slices. In
single slice view, spatial details and information from individual voxels may be obtained. In a
3D view, the original data may be viewed with 3 orthogonal slice planes. This orthographic 3D
view may also show high-resolution anatomical information if make available prior to the
functional scan. After proper preprocessing, the functional data may run as a movie on highresolution data in AC-PC or Talairach space as well as on surface visualizations. To inspect the
time course of individual voxels or regions-of-interest, various tools are available to easily
select interesting ROIs from any of the described visualizations. Selected raw time courses are
shown in time course windows together with incrementally updated bar plots showing estimated
beta values for main conditions. An event-related averaging plot for the current ROI is
visualized in the orthographic 3D view representation.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
Running Example Data Sets
The Turbo-BrainVoyager Installer CD includes two example data sets that can be used to
practice working with the various features of the software. After installation, the data sets are
stored in the "(My )Documents/TBVData" folder (if not deselected). The installers on our web site
do not include the sample data sets but you can get them there as a separate download. If you
download the exercise data, extract the .zip files in the "Documents/TBVData" folder. Since the
provided .TBV files support relative path names, it is, however, not critical where the sample data
will be installed.
TBV will run with a sample data set in the same way as during a real scanning session (it doesn't
know the difference). During scanning, TBV usually reads the next data volume as soon as it
becomes available. Note that in case of running sample data, the complete series of functional
volume data is already available on disk and, thus, the analysis will run likely much faster than in
the real scanning situation. In order to more realistically simulate the experience during a real
scanning session, one may want to set the ForceTRDelay option to "true" in the Statistics tab of
the TBV Settings dialog. You may also presss the R key during a running analysis in order to
switch between simulated true scanning speed and the maximally possible speed.
"Faces Houses" Data
This data set allows to localize in real-time the fusiform face area (FFA) and the
parahippocampal place area (PPA). Besides rest blocks, 2 blocks with images of faces and 2
blocks with images of houses/places are shown. To analyze this sample data set, select the TBV
file "NK_FFA_PPA_TAL-1.tbv" in the "TBV_FacesHouses" folder using the Set TBV File item in
the File menu. Then press the red Record button to start real-time analysis. If you want to speed
up processing, press the R key. The program always launches in multi-slice view. To become
familar with TBV, it is recommended to perform the following tasks:
Select regions-of-interest (ROIs) by dragging the mouse over any section of a slice.
Click CTRL-R to switch between ROIs visualized as rectangles or as marked voxels.
Add a new ROI by dragging a region while holding down the SHIFT key.
Replace the content of a Time Course Window by first clicking it to make it the active one followed by a
dragging operation.
Change the threshold of the displayed maps using the Threshold spin box in the lower right corner of the
program window.
Press CTRL-B to hide or show the beta plot section on the right side of Time Course Windows.
If the analysis of a run has been completed, right-click a time course window and select ROI GLM in the
context menu.
Zoom into a slice by clicking on it while holding down the ALT key. ALT-click again to go back to Multi-Slice
View.
Switch to the available Brain Views using the icons below the main window.
Switch to Volume View to inspect how the plots change dynamically in the Event-Related Averaging Plot.
You will also find a recorded animation on our web site demonstrating these and other
possibilities of Turbo-BrainVoyager. Furthermore, the TBV installer puts a more detailed tutorial
document "TBV_Exercise1_FacesAndHouses.pdf" in the "(My
)Documents/TBVData/TBV_FacesHouses" folder.
"Attention BCI" Data
This data set consists of several runs. The subject is asked to attend either a local or a global
rectangle displayed on the screen (see snapshot above). The first run is used to train a classifier
to associate the brain activity patterns evoked during the two tasks with the respective condition.
When the subject performs the attention task in subsequent runs, the trained classifier is used to
predict the condition from the evoked brain patterns. To analyze the first run used to train the
classifier, select the TBV file "ATTBCI_01_trainig.tbv" in the "TBV_SVMClassifier" folder using
the Set TBV File item in the File menu.
It is recommended to perform the following tasks:
Run through the data in as-fast-as-possible mode (this mode is set as default int the TBV file for this run).
During real-time analysis, inspect any region you desire. Note that it is difficult to find regions that clearly
discriminate between the two conditions "small" (attention to small rectangle) and "large" (attention to large
rectangle).
When the analysis of the run has been completed, define a ROI for training. Since this ROI should include
almost all grey matter voxels in the back of the brain, lower the threshold of the displayed maps, e.g. to a
value of "2.0" and turn on the contrast "small vs resting" and "large vs resting" in both directions (i.e. mark all 4
option boxes for these two contrasts).
Increase the value of the MultiSliceROIs spin box to 18. Now drag a rectangle at a slice in the middle of the
brain in such a way that it encompasses most of the posterior cortex (see snapshot above showing a specified
ROI in both rectangle and marked voxels view).
Enter the Multi-Voxel Pattern Classification dialog and prepare the training as described in
the SVM Training documentation (see also snapshot above).
After training the classifier, you may inspect the distributed weights of the SVM classifier
since the original map will be replaced by a map of SVM weights; increase the threshold to
see where high values are located (see snapshot below).
To analyze the second run - used to test the trained classifier - select the TBV file
"ATTBCI_02_testing_1.tbv" in the "TBV_SVMClassifier" folder using the Set TBV File item in
the File menu. Note that in the context of classifier applications, it is most convenient to set the
WatchFolder for all runs of one scanning session to the same output directory. In this case it is
easy to find the classifier output data from previous runs when preparing classifier testing. For the
sample data used, the target folder has been set to "ATTBCI_TBV_analysis" (within the
"TBV_SVMClassifier" folder) in the TBV files of all runs.
After selecting the TBV file for the first test run, perform the following tasks:
Open the Real-Time SVM Classification dialog.
Use the Browse button next to the Trained classifier text box and select the SVM file of the classifier trained
with the data of the previous run (e.g. "Model_ROI 1_small-large_8-8.svm", see also snapshot below).
Click the Predict button. The program now waits for data to analyze.
Click the Record button to start data analysis.
Observe the incremental predictions of the classifier. Note that the protocol of the test run(s) do not encode the
condition, i.e. it does not encode the task (all task epochs are coded with the same condition labelled as "2" in
the classifier output). In order to evaluate the classifier performance, the subject was asked to alternate the
"small" and "large" attention tasks.
Are all task epochs classified correctly? In the snapshot below, the accuraccy is 94% - Do you spot the one
trial predicted wrongly?
There are two more runs that can be used for testing in the same way as described above. Note
also that you can use the data from more than one run for training, i.e. you can use the data from
the first two runs for training and then test the classifier on the two additional runs. The TBV
installer puts a more detailed tutorial document "TBV_Exercise2_AttentionBCI.pdf" in the "(My
)Documents/TBVData/TBV_SVMClassifier" folder
Note. You may be surprised to see non-zero motion parameters in the Motion Correction
Window when analyzing the test runs (see snapshot above). This does not reflect real motion of
the subject at the begin of the scan (the subject actually does not move much) but happens
because the subsequent runs use the first (training) run as their target for motion correction.
While the subject itself does not move much as indicated by the motion parameters, there are
small incremental motion effects across runs (e.g. due to scanner gradient heating) and these
effects will be corrected by across-run motion correction.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
The Graphical User Interface
The following figure shows the main parts of the graphical user interface (GUI) of TurboBrainVoyager. Click on a region in the figure to obtain further information.
To start real-time data analysis, simply click the Record/Stop button. Note, however, that
several settings have to be specified before the analysis can be performed.
Turbo-BrainVoyager User's Guide
The Main Control Buttons
The most important options of the program are available with six basic buttons, Backward,
Record, Forward, Reload Data, Auto-Advance and Auto-Start. Further options are available in the
main menu, context menu, icons, and keyboard short cuts. For a detailled description of all
functions, see sections Menu Functions and Keyboard and Mouse Functions.
Function of Main Buttons
Record button. Starts real-time analysis according to the current single-run TBV
settings file. If the TBV settings file refers to a multi-run analysis (.mtbv file), the
multi-run analysis is performed on the basis of the results of two or more individual
runs.
Backward button. Switches to the previous single-run TBV settings file, if available. If
there is no previous run available, the button is shown in an inactive (grey-colored)
state. To run the new single-run settings file, press the Record button. In case that the
Auto-Start toggle button is on, the new settings file is executed immediately without
the need to press the Record button.
Forward button. Switches to the next single-run TBV settings file, if available. If there
is no new run available, the button is shown in an inactive (grey-colored) state. If a
new run is available, the button is shown in active mode and you can switch to the
new run by clicking the button. Note that if the Auto-Advance toggle button is on (see
below), the program switches automatically to the new run as soon as the data (and
the respective TBV settings file) becomes available. If also the Auto-Start toggle
button is on, the analysis of the new run is started immediately, otherwise you must
start the analysis by clicking the Record button.
Reload Data button. Reloads data of a run already analyzed before for further
inspection. The button is only enabled if the data belonging to the current TBV settings
file is available on disk in the respective TargetFolder.
Auto-Advance toggle button. If this button is on, the program switches to a new run
as soon as the respective single-run TBV settings file becomes available. If this button
is off, you can use the Forward button to switch to the new run or select a new
settings file using the Set New TBV File item in the File menu.
Auto-Start toggle button. If the program switches from the current run to another (old
or new) run, the analysis of the selected run is normally started by clicking the Record
button. If, however, the Auto-Start button is on, the selected run is analyzed
immediately without the need to press the Record button.
The Backward, Forward and Auto-Advance buttons do only work in specific settings (usually in
the context of the "IFIS" real-time system). It is advised to directly set the next TBV settings file
usint the File >Set New TBV File menu item. If subsequent runs use the same parameters
(number of slices, TR and so on), the easiest way to prepare the next run is to change the
settings in the current TBV file and to save the modified TBV file under a new name. To change
the current TBV settings file use the File > Edit TBV File button to enter the TBV Settings dialog
and change the necessary fields for the next run usually including the FirstFileName in the Data
Format tab, the StimulationProtocol entry (if different), NrOfVolumes entry (if different) and the
ProjectName text in the Time Course tab. For a more convenient and robust approach it is
recommended to prepare all TBV files required for a series of real-time runs ahead of time and
to switch for each run to the prepared TBV file. This will require only to change one field, the
FirstFileName entry in the Data Format tab.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
Menu Functions
The following menu functions can be used to quickly access important features of TurboBrainVoyager. Additional context menus are available by clicking the right mouse button (or
CTRL-Left-Mouse on Macs). Context menus are only accessible when not in real-time recording
mode. In the upper right corner of the program window, there are also two standard buttons for
minimizing and exiting the program. Between these two icons is a "Restore" icon, which can be
used to toggle between two sizes of the program window. This icon is relevant only for the
Windows version of the program since the Mac OS X and Linux versions allow to freely resize
the program window. The main control buttons in the left upper region control fundamental
operations, i.e. to start the analysis of a real-time scan.
Main menu
File
Set New TBV File. Changes current TBV file. Presents a File Open dialog,
which you can use to navigate to a new TBV settings file.
Edit TBV File. This option invokes the TBV Settings dialog.
Edit MasterTBV File . This menu item invokes the MasterTBV File dialog.
Rename DICOM Files. This option calls the Rename DICOM Files dialog.
VMR-VMR Coregistration. This option invokes the VMR-VMR Coregistration
dialog allowing to align an intra-session 3D data set with an extra-session
(e.g. AC-PC) transformed 3D data set, which is useful for preparing advanced
visualizations.
Neurofeedback... This menu item launches the Neurofeedback dialog that
offers various functions for presenting data to the subject during real-time
scanning.
Close. Removes the current analysis clearing all windows.
Exit. Quits the program.
Analysis
Colors Code Significance. A flag on the left side of this menu item shows
whether this mode is currently enabled. In this case, a standard red-to-
yellow color scale is used to visualize the significance of a voxel for selected
">" contrasts and a standard blue-to-green color scale is used to visualize
the significance of a voxel for "<" contrasts. Note that in this mode, it is not
visualized which contrast (or contrasts) are significant at a voxel in case that
more than one contrast is selected in the contrast window. You may turn
on/off this visualization mode also with the P toggle button.
Colors Code Contrasts. A flag on the left side of this menu item shows
whether this mode is currently enabled. In this case, each significant voxel is
visualized with the color of the contrast with the highest t-value. This allows
to quickly recognize, which contrast is the most significant at a particular
voxel. You may turn on/off this visualization mode also with the P toggle
button.
Log ROI Time Point Files (RTPs). If this option is turned on, a .RTP file is
saved for each time point to disk containing the mean signal values of all
currently selected ROIs. This can be used for custom software aiming at
further analyzing ROI data in real-time. The time point at which a .RTP file
was written can be identified by the time point value that is included in the
file name. The first value within a .RTP file specifies the number of ROIs at
that moment during real-time processing. This is followed by a series of
values corresponding to the number of available ROIs. Finally an integer
value is stored representing the condition of the current protocol defined at
that time point. (Note that the extension is the same as used for real-time
protocols, but ROI RTP and protocol RTP files are unrelated).
Log ROI Voxel Time Courses (ERT). If this option is turned on, the values
of all voxels within all currently selected ROIs are saved incrementally to
disk in a single .ERT file. This can be used for custom software aiming at
further analyzing ROI data at the voxel level in real-time.
Log Estimated ROI Betas (BTC). This option stores estimated beta values
(percent signal change transformed) from GLMs performed on the mean time
courses of all currently selected ROIs. The data is incrementally saved into a
single .BTC file.
Load VOI Definition File... This function allows to load VOI files previously
saved from TBV or .VOI files prepared with BrainVoyager QX. These files are
defined typically in stereotactic 3D (ACPC or Talairach) space. To work
properly, appropriate alignment files must be provided.
Save VOI Definition File... This function saves all current ROIs as 3D
volumes-of-interest (VOIs) to disk in a .VOI file. This option is only enabled if
full 3D data sets (intra-session, ACPC or Talairach space) are available. The
saved VOI files can be used for further analyses in BrainVoyager QX and they
can be reloaded for subsequent runs.
Load ROI Definition File... This function (re)loads definitions of regions-ofinterest (ROIs) previously saved to disk as .ROI files. A .ROI file contains for
each ROI a list of voxel coordinates. Since ROI definition are in recording
space and not in stereotactic space, they should be only reloaded for runs of
the same session and with the same slice position information.
Save ROI Definition File... This function saves all current regions-of-interest
(ROIs) to disk in a .ROI file. For each ROI, the coordinates of individual
voxels are stored in recording space (x and y coordinate within a slice and
the slice number as the z coordinate). At the end of a real-time run, this
function is called automatically to save the state of selected ROIs in a file
called "<ProjectName>.roi".
Remove ROI Time Course Plots. Removes all currently open ROI time
course plots and all associated ROIs.
Epoch-Based Averaging. This option determines how the baseline is
computed for the event-related averaging (AVG) plot shown in the 3D view
for the currently active ROI. If turned on, percent signal changes are
calculated for individual events/blocks with respect to the preceding
(baseline) signal level and the calculated percent signal changes are then
averaged across repetitions. If this option is turned off (default), a baseline
signal level is first computed as the average of the time segments before
each event/block and percent signal changes for individual events/blocks are
calculated with respect to this common baseline. The results of the latter
approach are more in line with those obtained from a General Linear Model
(GLM) analysis also estimating a generic baseline level from all available
baseline condition epochs.
Stimulation Protocol... This option invokes the Stimulation Protocol dialog.
Show ROI GLM Beta Plots. This shows a bar plot of beta values on the right
side of each ROI time course window (default). If turned off, the whole space
of a ROI time course window is used for the ROI time course itself.
SVM Training. Launches a machine learning tool allowing to train a SVM
classifier to associate patterns of activity with different classes (conditions).
Real-Time SVM Classification. Launches a real-time classification tool that
uses a trained classifier to incrementally predict the class to which a current
activity pattern belongs.
Post Processing. Launches tools to perform additional processing steps
after a real-time run has been completed to improve the quality of the data
beyond the pre-processing routines applied during real-time processing. The
processing steps include slice scan time processing and non-linear high-pass
filtering.
View
Multi-Slice View. The scanned first EPI or inplane images are shown in a
multi-slice arrangement with superimposed statistical data. This view may
also be selected by clicking the Multi-Slice View Icon button or by pressing
the F key.
Volume View. The EPI or inplane images are shown in three subwindows in
3D mode. The three subwindows show a sagittal, coronal and axial plane of
the data; the original slice data is stacked on top of each other and
interpolated to a 1mm x1mm x 1mm 3D data. This view may also be
selected by clicking the Volume View Icon button or by pressing the V key.
Anatomical Volume View. Shows dynamic contrast maps superimposed on
intra- or extra-session 3D data sets. To use this view, preparations have to
be performed prior to the functional measurements. This view may also be
selected by clicking the Anatomical Volume View Icon button or by pressing
the A key.
Surface View. Shows surface rendered representations of the brain. To use
this view, preparations have to be performed prior to the functional
measurements. This view may also be selected by clicking the Surface View
Icon button or by pressing the S key
Overlay On Inplanes. If coplanar inplane slices are available, the statistical
maps are superimposed on these inplanes. A flag on the left side of this
menu entry indicates whether this display mode is currently selected. If no
inplanes are available, this option is disabled. The inplanes are often T1weighted images not suffering from the EPI susceptibility artifacts. The same
function is also provided with the I toggle button.
Overlay On First EPIs. The statistical maps are superimposed on the first
functional volume of the EPI data of the current run. A flag on the left side of
this menu entry indicates whether this display mode is currently selected.
The same function is also provided with the I toggle button.
Show ROIs Using Rectangles. This option affects only multi-slice view; it
turns on visualization of ROIs as rectangles. This has the advantage that the
voxels within the region remain visible (are not marked as when using the
Using ROIs As Marked Voxels option) but it has the disadvantage that it is not
shown which voxels precisely are included in a ROI. Switching between the
different ROI visualizations can be also acheived by pressing CTRL-R.
Using ROIs As Marked Voxels. This option affects only multi-slice view; it
turns on visualization of ROIs by marking each voxel belonging to the ROI
with a single color. This has the advantage that the voxels making up an ROI
are precisely visible but it has the disadvantage that the voxels (e.g. current
map values) are not visible well; zomming in a slice (single-slice view) is a
good compromise since the enlarged view shows voxels usually large enough
to visualize both the rectangle around a voxel labeling it as belonging to a
ROI as well as the color inside the rectangle reflecting the voxel's map value
or anatomical intensity value. Switching between the different ROI
visualizations can be also acheived by pressing CTRL-R.
Plugins
This menu shows a list of all available plugins. Select one of the available
files to start the respective plugin.
Help
User's Guide. Invokes a documentation viewer showing the TurboBrainVoyager User's Guide.
License Information. Shows information about the license.
About Turbo-BrainVoyager. Invokes the Turbo-BrainVoyager splash screen
with version information (on Mac OS X this item is located in the TurboBrainVoyager menu on the left side of the menu bar).
Context Menus
Help topics. Invoke the User's Guide.
Save as Bitmap.... Saves the program window or the sub-window under the mouse to
disk. Presents a "Save As" dialog. Note that this command is context-dependent: If
you invoke the context menu over the contrasts overlay window or any of the time
course windows, only the content of the respective window is saved. If you invoke it at
any other part of the program window, the whole content of the program window is
saved.
Log ROI time courses. Flag indicating whether the time course of selected ROIs
should be incrementally saved. The saved data can be used for further (real-time)
processing, i.e. with custom neurofeedback software.
Turbo-BrainVoyager User's Guide
Keyboard and Mouse Functions
Keyboard and mouse functions can be used to quickly access important features of TurboBrainVoyager. Short cuts are described below allowing to quickly switch between available
views on the data. Then options are described available within each specific brain view. Finally
general options are presented, which are valid for all views. Finally options for Time Course
Windows are described.
Switching Brain Views
F key. Switches to the Multi-Slice View of the data. The same function is also provided
with the Multi-Slice View item in the View menu and with the Multi-Slice View icon
located below the Brain Window. The Multi-Slice View shows the (incrementally)
calculated contrast maps on original slices in a multi-slice arrangement allowing to
inspect the whole data at once. As default, the EPI images from the first measured
volume are shown in the multi-slice arrangement but the EPI images may be replaced
by higher-resolution inplane (T1 or T2) images from a scan prior to functional
measurements (see "I" button below). It is possible to zoom into a single slice by
clicking in a slice while holding down the SHIFT key (Single-Slice View, see below).
V key. Switches to the Volume View of the data. The same function is also provided
with the Volume View item in the View menu and with the Volume View icon located
below the Brain Window. The Volume View shows (incrementally) computed statistical
maps in three subwindows in 3D mode. The three subwindows show a sagittal, coronal
and axial plane of the data, which is interpolated to a 1mm x 1mm x 1mm data set
from the original data. This view uses only data from the original slice positions
without any translation or rotation transformation. As default, the EPI images from the
first measured volume are used to build the orthographic 3D view but the EPI images
may be replaced by higher-resolution inplane (T1 or T2) images from a scan prior to
functional measurements (see "I" button below).
A key. Switches to the Anatomical Volume View. The same function is also provided
with the Anatomical Volume View item in the View menu and with the Anatomical
Volume View icon located below the Brain Window. This option is only available if an
intra-session, ACPC or Talairach transformed 3D data set is loaded. As opposed to the
standard Volume View, the statistical data is projected on a full high-resolution 3D
data set in this visualization. The projection uses a spatial transformation matrix and
eventually a Talairach transformation step. Specifications in the TBV settings file
determine whether the anatomical 3D data resides in intra-session, AC-PC or Talairach
space and requires appropriate transformation files.
S key. Switches to the Surface View. The same function is also provided with the
Surface View item in the View menu and with the Left Hemisphere and Right
Hemisphere Surface View icons located below the Brain Window. This option is only
available if meshes are loaded, which must be prepared in BrainVoyager QX. The
meshes are typically representations of the left and right cortical sheet. This option
furthermore requires that a 3D data set is also loaded residing in the same space as
the cortex meshes. The statistical data is projected on the cortex meshes by using the
same transformation pipleline as used for the inplane, AC-PC or Talairach anatomical
3D data set used in the Anatomical Volume View.
Options in Multi-Slice View
Dragging rectangle with left mouse button. Drag a rectangle on a slice to obtain the
average time course of pixels within the region. The time course is shown in one of
the Time Course Plot windows. If no time course is visible yet, the data will be shown
in the top most Time Course Window. New drag operations will replace the data in the
current ROI window with the average time course of the newly selected voxels. If a
rectangle is dragged while the SHIFT key is down, the time course of the selected
voxels is shown in a new Time Course Window. Note that the mapping between a
rectangle and the corresponding Time Course Plot window is established by the color
of the drawn rectangle, which is also shown in the lower corner of the Time Course
Plot window. If multiple Time Course Windows show data, you can make one of them
the current ROI window by clicking with the left mouse button in its window. As
default, the averaged time course of the significant (color-coded) pixels within the
dragged rectangle are selected. If no significant pixels are inside the rectangle, the
time courses of all pixels in the rectangle are chosen. Slices above and below the
current slice can be included for ROI selection by using the xx option.
I button. Switches between scanned EPI images (first volume of current run) and
images from a scan with higher-resolution T1 or T2 inplane images. The same function
is also provided in the View menu with the Overlay On Inplanes and Overlay On First
EPIs items.
ALT-Click. Click at any position within a slice while holding down the ALT key to switch
to Single-Slice View showing an enlarged view of the selected slice within the area of
the view window. In order to leave Single-Slice View switching back to Multi-Slice
View, SHIFT-Click the zoomed slice.
CTRL-R. Toggles the visualization of ROIs between rectangle mode and marked voxel
mode (see also corresponding items in View menu).
Options in Single-Slice View
CMD/CTRL-Click. Click a pixel on the enlarged slice view while holding down the CTRL
(on Windows and Linux) or CMD (on Mac) key to include or exclude the respective
voxel from the current ROI.
PgUp/PgDwn or CursorKey-Left/CursorKey-Right. Use these buttons to switch
slices in zoomed single-slice mode.
Dragging rectangle with left mouse button. Although this view is often used to
select individual voxels, you may also drag a rectangle on a slice to obtain the
average time course of pixels within the region in the same way as in Multi-Slice View.
I key. Switches between scanned EPI images (first volume of current run) and images
from a scan with higher-resolution T1 or T2 inplane images. The same function is also
provided in the View menu with the Overlay On Inplanes and Overlay On First EPIs
items.
ALT-Click. Click at any position within the slice while holding down the ALT key to
switch back to Multi-Slice View.
CTRL-R. Toggles the visualization of ROIs between rectangle mode and marked voxel
mode (see also corresponding items in View menu).
Options in Volume View
Mouse navigation. Click in any of the three orthographic sub-view windows (sagittal,
coronal and axial) windows. Navigate to any region by moving the mouse left/right
and up/down while holding down the left mouse button.
CursorKey navigation. Navigate stepwise through slices of the Volume View moving
left/right with the LEFT and RIGHT cursor keys, and up/down with the UP and DOWN
cursor keys. To move forward/backward, use the UP and DOWN cursor keys while
holding down the SHIFT button.
CTRL-Click. Click on a voxel in any of the three sub-views with the left mouse button
while holding down the CTRL key to select a region-of-interest (ROI). If a significant
(color-coded) voxel is hit, a functional cluster with only significant pixels will be
selected. If a non-significant voxel is hit, all voxels within a 3D cube around the voxel
will be included in the ROI. The averaged time course of the voxels within the ROI will
be shown in the current Time Course Window. To put the data of a selected ROI in a
new Time Course Window, hold down both the CTRL and SHIFT key.
I button. Switches between scanned EPI images (first volume of current run) and
images from a scan with higher-resolution T1 or T2 inplane images. The same function
is also provided in the View menu with the Overlay On Inplanes and Overlay On First
EPIs items.
Options in Anatomical Volume View
Mouse navigation. Click in any of the three orthographic sub-view (sagittal, coronal
and axial) windows. Navigate to any region by moving the mouse left/right and
up/down while holding down the left mouse button.
CursorKey navigation. Navigate stepwise through slices of the Volume View moving
left/right with the LEFT and RIGHT cursor keys, and up/down with the UP and DOWN
cursor keys. To move forward/backward, use the UP and DOWN cursor keys while
holding down the SHIFT button.
CTRL-Click. Click on a voxel in any of the three sub-views with the left mouse button
while holding down the CTRL key to select a region-of-interest (ROI). If a significant
(color-coded) voxel is hit, a functional cluster with only significant pixels will be
selected. If a non-significant voxel is hit, all voxels within a 3D cube around the voxel
will be included in the ROI. Note that functional ROI selection does not operate in the
space of the Anatomical Volume View (e.g. Talairach space), but in the space of the
original slice data. The coordinates of the selected voxel in intra-session, AC-PC or
Talairach space are transformed back into the original space of the current functional
measurement and the selection of voxels is performed in that space according to the
rules described earlier. After having expanded the selection in the data's native space,
the coordinates of the marked voxels are forward transformed to be visualized
adequately in the space of the Anatomical Volume View. The averaged time course of
the voxels within the ROI will be shown in the current Time Course window. To put the
data of a selected ROI in a new Time Course Window, hold down both the CTRL and
SHIFT key.
Options in Surface View
Mouse navigation. Move the mouse left/right and up/down to rotate the viewpoint
around the mesh(es). Hold down the left mouse button and move the mouse up and
down and left and right to perform translations of the viewpoint. Hold down both the
SHIFT and CTRL keys and move the mouse up and down in order to move the
viewpoint closer or further away (zooming).
CursorKey navigation. Rotations of the viewpoint can be performed also in small
steps by clicking the left/right and up/down cursor keys.
CTRL-Click. Click on a mesh while holding down the CTRL key to select a region-ofinterest (ROI). If a significant (color-coded) vertex is hit, a functional cluster with only
significant vertices will be selected. If a non-significant vertex is hit, a region around
the vertex will be included in the ROI. Note that functional ROI selection does not
operate on the surface, but in the space of the original slice data. The coordinates of
the vertex are transformed back into the space of the current functional measurement
and the selection of voxels is performed in that space according to the rules described
earlier. After having expanded the selection in the data's native space, the coordinates
of the marked voxels are forward transformed to be visualized on the mesh. The
averaged time course of the voxels within the ROI will be shown in the current Time
Course Window. To open a new time course window, hold down both the CTRL and the
SHIFT key.
Statistical options
P key. Toggles between significance color coding and multi-map color coding in the
View window. The same function is also provided with two entries in the Analysis
menu, namely Colors Code Significance and Colors Code Contrasts. If colors code
significance, a red-to-yellow range of colors is used for gr contrasts, and a typical
blue-to-green range of colors for lt contrasts. Since the same color range is used for
all contrasts, it is not recognizable which contrast is shown at a particular voxel. In
colors code contrasts mode, each significant voxel is visualized with the color of the
contrast with the highest t-value.
CTRL-CursorKey-Up. Increases the statistical t threshold by a value of "0.2". The
same function can be also performed using the Threshold spin box.
CTRL-CursorKey-Down. Decreases the statistical t threshold by a value of "0.2". The
same function can be also performed using the Threshold spin box. The value can not
be set lower than t = 1.0. The current value of the threshold is shown in the
Information Window and in the Threshold spin box.
Time Course Windows
Mouse Selection. Clicking within a Time Course Window makes the respective window
the current one. When selecting a region-of-interest in one of the Brain Views, the
time course data is shown in the current Time Course Window replacing the data
previously shown. When holding down the ALT key when selecting a ROI, the data of
the new region is shown in a new Time Course Window. The number of time course
windows corresponds directly to the number of simultaneously visualized ROIs. The
data of the current Time Course Window is also used to calculate event-related
averages, which are shown in the Volume and Anatomical Volume Views. If you have
selected one of these views, you can thus inspect event-related averages for all
currently available ROIs by clicking within the respective Time Course Window.
CTRL-B key combination (toggle). Shows/hides the beta bar plot on the right side of a
Time Course Window. The bars of the beta plot are estimates of the beta values of the
respective main conditions of the protocol. The color of the bars matches those defined
for the corresponding condition in the protocol.
CTRL-N key combination. Expands the horizontal space for the beta bar plot. Use this
option if the bars are drawn to closely to each other or if you want to see the condition
names below the plot without interference with names of other conditions. This option
does not work in separate Time Course Windows detached from the main window,
which can be freely resized.
CTRL-M key combination. Shrinks the horizontal space available for the beta bar plot.
Use if you want to use more space in the window for drawing the ROI time course.
This option does not work in separate Time Course Windows detached from the main
window, which can be freely resized.
Miscelleanous
R key. The speed of real-time data processing depends normally on how fast the data
arrives from the scanner. With the R key, the ForceTRDelay option can be turned on,
which forces TBV to wait the time specified in the TR value in the TBV Settings File
before progressing with reading the next data point (volume). This option can be, for
example, be used when rerunning the real-time analysis to slow down the program,
otherwise it will work as fast as possible since all data is available. The option might
also be helpful in a real situation because it can be used to avoid that the program
"peeks" into not fully written data files, which seem to slow down processing in some
situations. The key can be pressed again to stop the ForceTRDelay mode. In this case,
the program will wait until the time N*TR has elapsed with N reflecting the current
data point.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
Visualization of Contrast Maps on Brain Views
The Brain Window shows results of incremental statistical data analysis as overlays - like a
movie - on various display formats called views. The primary view is the Multi-Slice View which
is always shown first after starting real-time analysis provides a good overview of the brain
data and overlayed statistical results. To inspect details at the voxel level, the Single-Slice View
is most appropriate. A three-dimensional orientation in space is provided by the Volume View.
While the Volume View shows the data in three orthographic views in the original slice space,
the Anatomical Volume View allows to show the statistical data in a more abstract highresolution 3D space, such as AC-PC or Talairach space. The Surface View provides advanced
visualization of the statistical data on previously reconstructed cortex mesh representations.
The displayed contrast maps are automatically updated after each data point has been obtained
and processed using a recursive least squares General Linear Model (RLS GLM). A "data point"
here refers to one measurement of all functional slices and is also called a (functional) volume.
The number of the currently processed data point can be inspected in the Information Window
together with the elapsed time from the start of the processed run.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
Multi-Slice View
In Multi-Slice View, recorded slices are shown in a matrix arrangement allowing to inspect
computed statistical results in the whole brain at once. The values of the NrOfRows and
NrOfColumns in the Data Format tab of the TBV Settings dialog determine how the data is
arranged in Multi-Slice View. In order to show all slices (recommended), the product of number
of rows and number of columns should be equalto (or greater than) the number of recorded
slices specified in the NrOfSlices parameter. Since the Brain Window is square in the Windows
version of TBV, pixels in slices may not be square in case that the number of rows and columns
are not the same. To switch to Multi-Slice View, click the Multi-Slice View Icon located below the
Brain Window (see snapshot below) or press the F key.
The snapshot above shows the Brain Window with an example of a Multi-Slice View with a 5
rows x 6 columns arrangement displaying all 30 slices recorded in this particular example.
During or after real-time processing, you can select regions-of-interest by dragging a rectangle
around "significant" pixels. The averaged time course of the significant voxels within the
specified ROI is immediately shown in one of the Time Course Windows. If you specify a ROI
which does not contain any significant voxels, the Time Course Window shows the average of all
voxels within the rectangle. Time Course Windows are continously updated for the selected ROI
until a new ROI replaces its content. Note that additional slices above and below the current
slice may be used to define ROIs by dragging if the value of Multi-Slice ROI Selection is larger
than "1". This parameter can be set in the TBV Settings dialog prior to a functional run or
directly modified using the MultiSliceROIs spin box within the input panel at the bottom of the
program window.
To visualize several ROIs simultaneously, hold down the ALT key while dragging a rectangle with
the left mouse. If multiple ROIs are selected, you can make one of them the current one by
clicking in the respective Time Course Window. Specified ROIs can be identified because they
are drawn in color. In order to relate corresponding information with each other, a small
rectangle in the same color as the ROI is also drawn in the left lower part of a Time Course
Window.
Note on multiple ROI selection: Since the ALT key triggers on some Linux systems a movement
operation of the underlying Window, ROI selection should be performed on these systems in the
following order: first start the dragging by clicking with the left mouse, then drag the rectangle
around the region-of-interest and at any time before releasing the mouse key, press and hold
the ALT key.
Visualizaing on EPI Images or High-Resolution Inplane
Images
As default, statistical contrast maps are always visualized on the first recorded set of functional
(EPI) slices (see snapshot above for en example). The first EPI volume is used for display since
the first scan of each slice is T1-saturated and, thus, shows structural details not visible in later
measurements (if short TR's are used). For better visualization of anatomical details, coplanar
(T1 or T2 weighted) inplane images may be recorded prior to functional runs. Coplanar images
are scans with the same slice positions as used for the subsequent functional recordings. If
coplanar images are available, you may toggle between EPI and coplanar images using the
Overlay On First EPIs and Overlay On Inplanes items in the View menu or press the I (for
"inplane") button.
NOTE: If time is available, it is advisable to scan complete high-resolution 3D images instead of
coplanar images since these scans provide more details in all dimensions and allow visualizing
the data in AC-PC or Talairach space.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
Single-Slice View
This view shows a single slice from the multi-slice arrangement in the whole space of the Brain
View. The enlarged view allows to examine and modify regions-of-interest at the voxel level,
which may be important for advanced applications such as neurofeedback. There is no icon or
keyboard short cut to select this view. In order to switch to Single-Slice View you must select a
slice in the Multi-Slice View by clicking at any position inside a target slice while holding down
the SHIFT key. You may switch back to Multi-Slice View by SHIFT-clicking anywhere within the
zoomed slice. Once in Single-Slice View, you may browse through the available slices one by
one by using the PgUp and PgDn keys or Cursor-Left and Cursor-Right keys.
The snapshot above shows an example of the Slice-Based View together with a snapshot on the
right of the same slice in Multi-Slice View. The whole space of the Brain Window is used to
display the selected slice. Note that the voxels belonging to a ROI are now highlighted as small
colored rectangles filled with statistical or anatomical information. This visualization allows at
the same time inspection of which voxels belong to a ROI as well as inspection of the
information "inside" marked voxels. The most important feature of Single-Slice View is that an
ROI can be altered at the voxel level by clicking on a pixel while holding down the CTRL key. If
the CTRL-clicked pixel was not yet included in an ROI, it is added to the list of voxels of the
current ROI. If the voxel belongs already to the current ROI, it is removed from the list of
voxels. Note that you can specify the current ROI by clicking in the associated Time Course
Window.
The snapshot above shows parts of the program window (size 2, 1280 x 1024) with the same
slice as shown above together with the time courses and beta bar plots of two ROIs on the right.
The two ROIs shown in the first snapshot have been edited to become bilateral ROIs using CTRLclicking of the respective voxels.
Note that if a voxel is clicked without holding down the CTRL key, the list of voxels of the
current ROI will be replaced by a list containing only the single selected voxel. Clicking in this
way on different voxels allows to quickly inspect individual voxel time courses. Note that you
can also define new ROIs by clicking a voxel while holding down the ALT key. Although the
Single-Slice View is particularly well suited to define and inspect ROIs at the voxel level, you
may also use the same rectangle dragging approach to define ROIs as described for the MultiSlice View.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
Volume View
In Volume View, recorded slices are stacked on top of each other to form a 1 mm iso-volume.
In the snapshot below the individual slices are visible as horizontal stripes, which are due to
interleaved slice acquisition. In the example below, the original EPI slices are shown. If T1 or T2
weighted inplanes are recorded prior to the functional runs, it is possible to show a stacked 3D
view of these inplanes instead of the EPI slices by clicking on the Overlay On Inplanes item in
the View menu. To switch back to the functional slices (first measured volume), click the
Overlay On First EPIs item in the View menu; alternatively, you may use the I key to toggle
between the two views. If time is available for performing an extra scan prior to functional
runs, it is recommended to record a full 3D anatomical data set instead of an inplane data set. A
high-resolution 3D scan can be used for advanced visualizations in the Anatomical Volume View.
To switch to Volume View, click the Volume View Icon located below the Brain Window (see
snapshot above) or press the V button. To navigate in Volume View, click with the left mouse
button in one of the three subwindows. The yellow cross highlights the current voxel, which
determines the views shown in the respective subwindows. The subwindows display three "cuts"
through the data running orthogonally through the current voxel providing a sagittal, coronal and
axial view on the brain. Within a subwindow, you may move the mouse while holding the left
mouse button down to quickly change the current voxel, which immediately update the slice
view in the other two subwindows, respectively.
The selection of ROIs is different in Volume View as compared to Multi-Slice View: To specify a
ROI, click with the left mouse button on a voxel within a desired region while holding down the
CTRL key. The selected ROI is marked with a rectange and the averaged time course of all ROI
voxels is shown in a corresponding Time Course Window in the same way as described for the
Multi-Slice View. You may inspect the selected ROI in other visualizations by clicking on one of
the view icons. Since ROI selection is always performed on the raw slice data, the value of the
Multi-Slice ROI Selection option determines how many slices will be incorporated for ROI
definition.
Event-Related Averaging Plot
The Volume View also shows an Event-Related Averaging Plot in the lower left subwindow. For
the current ROI, this plot depicts the average hemodynamic response evoked by a certain
stimulus event or condition for the last specified ROI. In order to relate corresponding
information with each other, a small rectangle drawn in the same color as the corresponding
ROI is shown in the left lower corner of the Event-Related Averaging Plot. The plot shows a
curve for each main event/condition of the protocol (the first condition is not shown because it
typically defines periods of a baseline condition). The color of each curve matches the color of
the one defined for the respective condition in the protocol. If an event or condition occurs the
first time, the fMRI signal values are shown as percent signal changes but the standard error
bars are set to zero. If the same event or condition occurs subsequently the size of the error
bars will be calculated and updated together with the amplitude values.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
Preparing Advanced Visualizations
TBV allows to visualize statistical maps on various brain views. The Single Slice View and
Volume View (stacked slices) are always available when analyzing data. The Anatomical Volume
View and Surface View, however, require additional preparatory steps, which are described
below in the context of typical scenarios. These options not only provide the possibility of
advanced 3D visualizations but also allow to use volumes-of-interest (VOIs) across scanning
sessions.
Note: The advanced visualization options are only available if appropriate slice positioning
information is available for both the intra-session functional and 3D anatomical data sets.
Furthermore, most scenarios currently require the use of BrainVoyager QX.
Scenario 1 - Visualizing on Intra-Session 3D Anatomical Data
Set
Visualizing statistical maps on a high-resolution 3D data set allows to localize active clusters
more accurately. This scenario requires that an anatomical scan is performed in the same
scanning session prior to subsequent functional runs of the subject. At present, you must create
a VMR file from the raw data using BrainVoyager QX. The 3D anatomical scan must have a
resolution of 1 mm in all dimensions. If this is not the case, use BrainVoyager QX to "iso-voxel"
the 3D data to 1mm voxels first. TBV will coregister the functional data to the 3D anatomical
scan at the beginning of a real-time run. This requires proper slice positioning information for
both the functional data and the 3D anatomical data set. For the 3D data set a ".POS" file
specifying the slice position of the anatomical data set is automatically created when creating
the VMR file in BrainVoyager QX. For further information, sent an email to
goebel@brainvoyager.com. When subsequently getting information about the slice positions of
the functional run(s), TBV is automatically coregistering the functional and anatomical data set.
To enable the intra-session scenario for same-session functional analyses, select entry "1" in
the Overlay on VMR mode combo box of the VMR-SRF tab in the TBV Settings dialog (see
snapshots below). This will enable two (or three) fields for specifying the necessary files for
intra-session visualization. To select the slice position (.POS) file of the anatomical 3D data set,
click the Browse button on the right side of the IntraSessionVMRPosFile text box (see snapshots
below). To specify the anatomical file itself, use the Browse button on the right side of the
IntraSessionVMRFile text box. The anatomical 3D data set must be in BrainVoyager's native VMR
format (or in Analyze format for the ANALYZE_NW data format). To update the TBV Settings file
with the new settings, click the Save button in the lower right corner.
Data Format Specific Instructions
SIEMENS_DICOM_MOSAIC and GE_HDXT_DICOM. Formats based on DICOM files contain all
necessary positioning information. When creating a VMR file both required input files are
generated, a VMR data file and a slice position POS file. At present, the creation of these filese
requires BrainVoyager QX. Use the Browse button on the right side of the
IntraSessionVMRPosFile text field and the IntraSessionVMRFile text field to select the created
POS and VMR files, respectively (see snapshot below).
PHILIPS_ANALYZE_DRIN. The Philips real-time export generates a series of Analyze volume
files that do not contain slice positioning information for the functional data. In order to
nonetheless obtain slice positioning information, one needs to run a short scan of a few seconds
(one functional volume is sufficient) to generate a standard .REC/.PAR functional data set. Note
that this scan must use exactly the same slice positioning parameters as used for the
subsequent real-time runs producing Analyze files. Using BrainVoyager QX, a functional (FMR)
project needs to be created from the functional .REC/.PAR data that produces (next to other
files) a proper slice positioning POS file for the functional data. Use the Browse button on the
right side of the IntraSessionFMRPosFile text field and select the generated POS file for the
functional data (see snapshot below).
Processing of the intra-session 3D anatomical data proceeds similar as for other data formats. A
performed intra-session anatomical scan will produce a standard .REC/.PAR data set. Use
BrainVoyager QX to generate a VMR project from this data resulting in a VMR as well as a POS
file. If BrainVoyager QX detects that the anatomical data does not contain 1 mm cubic voxels, it
will suggest to "iso-voxel" the data. You need to accept this suggestion, otherwise TBV will not
visualize the data correctly. The correct VMR file will be identifiable by a "_ISO" label in the file
name. BrainVoyager will also suggest to transform the 3D data into standard neurological
format by suggesting a "To SAG" transformation step. Even if your data is recorded as sagittal
slices, you should accept this suggestion since TBV assumes that functional and anatomical data
is stored in radiological convention (left-is-right) and not in neurological convention (left-is-left)
and the generated .POS file also follows this assumption. The resulting VMR file will be
identifiable by a "_SAG" label in the resulting file name. In order to match the left-right
convention of the functional data to the anatomical data, you also need to keep the default
setting Flip AP axis when selecting the real-time functional data in the Data type specific fields
of the Data Format tab (see snapshot below, right side). Note also that Turbo-BrainVoyager
does not guarantee knowledge about the left/right convention. If you want to be sure about this
use additional measures (such as placing vitamin capsules that are visible in MR images on one
side of the head). When the POS and VMR files for the intra-session anatomical data are
available select them using the Browse button on the right side of the IntraSessionVMRPosFile
text field and the IntraSessionVMRFile text field, respectively (see snapshot below, left side).
SIEMENS_NW. In the context of this format that is used on older Siemens scanners, the 3D
data set is stored as an Analzye (.img) file together with an automatically generated proper
.POS file based on an export program developed by Nikolaus Weiskopf. For this format, the use
of BrainVoyager QX is not required. Use the Browse button on the right side of the
IntraSessionVMRPosFile text field and the IntraSessionVMRFile text field to select the
automatically created POS and IMG (Analyze) file, respectively (see snapshot below).
When subsequently running functional real-time analyses, the Anatomical Volume View icon will
be enabled (third icon from the left side in the snapshot below). Click the icon to switch to the
Anatomical Volume View visualization in intra-session 3D space.
Scenario 2 - Visualizing on AC-PC Space 3D Anatomical Data
Set
Visualizing statistical maps on a AC-PC transformed high-resolution anatomical data set allows
to view activation patterns in a common "near-Talairach" space while keeping the geometry of
the subject's brain intact. As in the intra-session scenario, this visualization option requires
scanning a 1 mm 3D data set prior to the functional runs. The 3D data set is necessary for
computing a AC-PC spatial transformation (.TRF) file. The AC-PC transformation file can be
either produced from the 3D data set itself (scenario 2a) or by automatically aligning it with
another AC-PC data set (scenario 2b) of the same subject obtained in an earlier session. The
AC-PC transformation in scenario 2a has to be done in BrainVoyager after the anatomical data
set has been performed and before the functional runs are started. In scenario 2b the
transformation file can be calculated directly within TBV since a different AC-PC transformed
data set is already available from a previous session. The creation of the AC-PC transformation
file for scenario 2b can be performed in TBV with the aid of the VMR-VMR Coregistration dialog,
which can be invoked by clicking the VMR-VMR Coregistration item in the File menu.
Use the Browse button on the right side of the Intra-session VMR (Source) text field to select
the 3D data set measured in the current session. Use the Browse button on the right side of the
AC-PC VMR (Target) text field to select the AC-PC transformed data set from a previous session.
The name of the resulting transformation (.TRF) file can be edited in the Transformation file
(Result) text field. To start the alignment, click the GO button. When the alignment procedure
returns, the main window will show the transformed intra-session 3D data set, which now
should fit the extra-session AC-PC data set. To check whether the alignment was successful, you
can repeatedly press the F8 key to toggle between the two data sets.
To enable visualizing statistical maps on a AC-PC data set, select entry "2" in the Overlay on
VMR mode combo box of the VMR-SRF tab in the TBV Settings dialog (see snapshot below). This
will disable the IntraSessionVMRFile entry but enables the ACPCTransformationFile and
ACPCVMRFile entries. Use the respective Browse buttons to select the AC-PC transformation
(.TRF) file and the AC-PC anatomical 3D (.VMR) file, respectively.
When subsequently running functional real-time analyses, the Anatomical Volume View icon will
be enabled as in scenario 1. When the icon is clicked, the Anatomical Volume View will show
now the specified AC-PC data set instead of the intra-session 3D data set.
Scenario 3 - Visualizing on Talairach Space 3D Anatomical
Data Set
Visualizing statistical maps in Talairach space allows to view activation patterns in a common
space. It also allows to import or export volumes-of-interest (VOIs) in Talairach space, which is,
for example, important for neurofeedback applications since identified regions can be used in
later real-time sessions by reloading VOIs. As in the previously described scenarios, this
visualization option requires scanning a 1 mm 3D data set prior to the functional runs. The intrasession 3D data set is also here necessary for computing a AC-PC spatial transformation (.TRF)
file, which is used as the first step of Talairach transformation. As described above, the AC-PC
transformation file can be either produced from the 3D data set itself (scenario 3a) or by
automatically aligning it with another AC-PC data set (scenario 3b) of the same subject obtained
in an earlier session. In addition to the AC-PC file, a Talairach landmark (.TAL) file is finally
needed, which must be created at present with BrainVoyager QX. If Talairach normalization data
is available from a previous session - AC-PC 3D file, Talairach normalized 3D file, Talairach
landmark file - the only necessary step to be performed is the automatic creation of the AC-PC
transformation file, which can be performed in TBV as described above.
To enable visualizing statistical maps on the Talairach space 3D data set, select entry "3" in the
Overlay on VMR mode combo box of the VMR-SRF tab in the TBV Settings dialog (see snapshot
above). This will disable the IntraSessionVMRFile and ACPCVMRFile entries but enables the
ACPCTransformationFile, TalairachFile and TalairachVMRFile entries. Use the respective Browse
buttons to select the AC-PC transformation (.TRF) file, the Talairach landmark (.TAL) file and the
Talairach space anatomical 3D (.VMR) file, respectively.
When subsequently running functional real-time analyses, the Anatomical Volume View icon will
be enabled as in scenario 1. When the icon is clicked, the Anatomical Volume View will show
now the specified Talairach VMR data set. To visualize statistical maps in Talairach (or AC-PC
space), a combined transformation data structure is kept in memory,which allows to determine
corresponding voxels in raw data space for each voxel in AC-PC or Talairach space. Note that
statistical analysis (e.g. calculation of dynamic contrast maps) is always performed in raw data
space.
Visualizing on reconstructed cortex meshes
Visualizing dynamic statistical maps on cortex meshes is very attractive because it provides an
easy understandable 3D view of the brain. Surface meshes may be rotated and zoomed allowing
to inspect any desired region during real-time analysis. Cortex meshes must be created in
BrainVoyager QX prior to subsequent real-time analysis sessions with the same subject. Cortex
visualizations require one of the three scenarios described above, preferebly scenario 2 (AC-PC
space) or 3 (Talairach space). To use surface representations, one or two meshes may be
specified, typically one mesh for the left and one mesh for the right hemisphere. Note that the
meshes must be in the same space as is used in the Anatomical Volume View, i.e. the space of
the surfaces must match the space of the respective scenario.
In order to allow fast rotation and zooming operations, it is recommended to use downsampled
versions of the respective meshes, e.g. meshes produces in the initial step of cortex-based
alignment. This has been done in the example shown above as indicated by the "_SPH" part in
the mesh names.
When subsequently running real-time analyses, the Surface View icons will be enabled (see
snapshot above); if value "1" has been selected in the Overlay on SRF mode combo box of the
TBV Settings dialog, only the left surface icon will be enabled since only one mesh has been
specified. Click one of the Surface View icons to switch to the Surface View visualization. If both
icons are enabled, you may turn on/off display of one of the two meshes by clicking the
respective icon, but it is not possible to turn off both meshes at the same time.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
Anatomical Volume View
This view allows to visualize contrast maps on high-resolution 3D data sets, which must be
recorded prior to the functional runs. There are severl scenarios possible for using the
Anatomical Volume View including visualization on the intra-session 3D data, visualization on a
intra- or extra-session AC-PC or Talairach transformed data set (see snapshot below). For
details on how to prepare these scenarios, see section Prepare Advanced Visualizations. To
switch to this view, click the Anatomical Volume View Icon
located below the Brain Window (see snapshot below) or press the A key.
Navigation in Anatomical Volume View operates in the same way as in Volume View by moving
the mouse in one of the three sub-windows while holding down the (left) mouse button. The
yellow cross highlights the current voxel, which determines the slices shown in the sagittal,
coronal and axial (transversal) views.
The selection of ROIs also works as in Volume View: To specify a ROI (also called Volume-OfInterest or VOI in this view), click with the left mouse button on a voxel within a desired
(active) region while holding down the CTRL key. Unlike as in Volume View, the selected ROI is
visualized by showing all involved voxels in the same color as the ROI (see pink color in the
snapshot above at the position of the yellow cross). The VOI's time course is shown in a
corresponding Time Course Window in the same way as described for the Multi-Slice View. You
may inspect the selected ROI in other visualizations by clicking on one of the view icons. Note
that the amount of voxels included in the VOI definition depens on the value of the Multi-Slice
ROI Selection since ROI selection is always performed on the raw slice data. ROI selection and
visualization operates in three stages:
1. The position of the selected voxel is transformed back into a position within the
original slice data using a spatial transformation linking the two spaces.
2. Voxels in the neighborhood within the respective slice as well as slices above and
below (if Multi-Slice ROI Selection value > 1) are checked for inclusion within a
presepcified neighborhood.
3. Using the spatial transformation linking the original space with the anatomical
volume space, the positions of the determined ROI voxels are transformed
"forward" to mark corresponding voxels in the color of the respective ROI. In a
similar way, ROIs are also marked in all other visualizations, always using the same
ROI definition within the original slice data.
Event-Related Averaging Plot
As the Volume View, the Anatomical Volume View also shows an Event-Related Averaging Plot in
the lower left subwindow. For the current ROI, this plot depicts the average hemodynamic
response evoked by a certain stimulus event or condition for the last specified ROI. If multiple
ROIs are defined, click in one of the respective ROI Time Course Windows to make the
corresponding ROI the current one.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
Surface View
This view allows to visualize contrast maps on surface-rendered 3D models of the cortex (see
snapshot below). The cortex meshes may be rotated and zoomed providing both useful
overviews as well as detailled views on the brain. The meshes must reside in the same space
(e.g., intra-session, AC-PC, Talairach) as the 3D data set shown in the Anatomical Volume View.
The surface meshes must be prepared before the functional measurements using BrainVoyager
QX and specified in the TBV Settings Dialog, for details, see section Prepare Advanced
Visualizations.
To switch to Surface View, click one of the two Surface View Icons (see snapshot above) or
press the S button. Both icons will be enabled if two meshes are specified in the TBV Settings
Dialog, typically one mesh for the left and one for the right hemisphere. If only one mesh is
specified, only the left icon is enabled. If two meshes are available, you may show or hide one
of the two meshes by pressing the Left or Right Hemisphere Surface View Icon. You may
navigate in Surface View by using the mouse or keyboard. Moving the mosue cursor up / down
while holding down the left mouse button will translate the viewpoint. If in addition the SHIFT
key is pressed down, the mesh can be rotated and if both the SHIFT and the CTRL key are down,
the viewpoint moves towards or away the meshes (zooming).
To specify a ROI (also called Patch-Of-Interest or POI in this view), click with the left mouse
button on a desired region of a mesh while holding down the CTRL key. The selected POI is
visualized on the mesh by showing all involved mesh parts (triangles) in the same color as the
color of the respective ROI (see blue color in the snapshot above). The time course of a
specified POI is shown in a corresponding Time Course Window in the same way as described
for the Multi-Slice View. You may inspect the selected ROI in other visualizations by clicking on
one of the view icons. Note that the size of a POI depends on the value of the Multi-Slice ROI
Selection since ROI selection is always performed on the raw slice data. Mesh-driven ROI
selection and visualization operates in three stages:
1. The position of the selected mesh vertex is transformed back into a position within
the original slice data using a spatial transformation linking the two spaces.
2. Voxels in the neighborhood within the respective slice as well as slices above and
below (if Multi-Slice ROI Selection value > 1) are checked for inclusion within a
presepcified neighborhood.
3. Using the current spatial transformation, the positions of the determined ROI voxels
are transformed "forward" to mark corresponding vertices on the mesh in the color
of the respective ROI. In a similar way, ROIs are also marked in all other
visualizations using the same definition in the original slice data.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
Time Course Windows
Time Course Windows show the time course of regions-of-interest (ROIs) selected in one of the
brain visualizations in the Brain Window. The x-axis of a Time Course Window displays time
while the y-axis displays the fMRI signal strength (raw values). A Time Course Window is filled
from left to right with incoming data, i.e. it is updated as soon as a new data point is available.
The time course shown represents the average time course from all voxels in the corresponding
ROI. Each window corresponds to exaclty one ROI. The little rectangle in the left lower corner of
the window indicates the ROI from which the time course has been drawn. The matching ROI is
demarcated in the Brain Window with the same color. If the rectangle is filled, the respective
Time Course Window and its associated ROI is made the current one. The current window has a
special status. If a new ROI is selected in one of the brain views without holding down the ALT
key, the current ROI is replaced by the newly selected ROI and its time course is shown in the
current Time Course Window. Furthermore, the time course of the current ROI is used to
calculate event-related averaging data, which is displayed in the lower left sub-window of the
(Anatomical) Volume View. Any of the available Time Course Windows can be made current by
clicking into the respective window. This will fill the small rectangle while the rectangles in all
other windows are shown unfilled.
Note on multiple ROI selection: Since the ALT key triggers on some Linux systems a movement
operation of the underlying Window, ROI selection should be performed on these systems in the
following order: first start the dragging by clicking with the left mouse, then drag the rectangle
around the region-of-interest and at any time before releasing the mouse key, press and hold
the ALT key.
If enabled (default), a Time Course Window also shows estimated beta values for main
conditions of the protocol as a bar graph on the right side. These beta values are estimated by a
incremental General Linear Model using the time course data plotted on the left side. The beta
bar plots are updated on the fly, i.e. the beta values are re-calculated as soon as new data
becomes available. The bars reflect mean per cent signal change with respect to the baseline
signal level (modeled by a constant term predictor). The colors of the bars reflect the colors of
the respective conditions defined in the protocol. The names of the conditions are also shown
below each bar. The beta bar plot can be turned on/off by pressing the CTRL-B key combination.
The horizontal space reserved for the bar plot can be adjusted by pressing CTRL-N (enlarge
space) and CTRL-M (shrink space).
After real-time analysis has been completed, a context menu can be invoked by right-clicking
within a Time Course window. From the context menu, a ROI GLM analysis can be launched
providing additional details as text (tables) and graphics.
Note that there are maximally three window slots available to show ROI time courses embedded
in the main program window. If enabled, the plots of motion correction parameters will use one
of the window spaces. Eventually (normally only in the context of IFIS) another window will be
used to show behavioral data (button presses). If more ROI time courses are requested by ALTselection in the Brain Window, pop-up windows will appear to display the respective time course
data. You may close these Time Course Windows by clicking the Close icon in the window's title
bar.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
The Motion Correction Window
This window shows the results of the detection and correction of small head movements during
real-time processing. The window is visible only if 3D motion correction is enabled in the TBV
settings file. During 3D motion correction all functional volumes are aligned in space by rigid
body transformation to the first recorded volume. The detected head motion of a volume with
respect to the reference volume results in 3 translation and 3 rotation parameters. These values
are used to translate and rotate the respective volume accordingly in order to "undo" the
detected head motion. During real-time analysis, these six estimated parameters are displayed
incrementally in the motion correction window. The 3 translation and 3 rotation parameters are
color-coded as follows:
red -> translation in X direction
green -> translation in Y direction
blue -> translation in Z direction
yellow -> rotation around X axis
magenta -> rotation around Y axis
cyan -> rotation around Z axis
Note that the axis are defined in image space (i.e. not in Talairach space): X refers to the
image left-to-right direction, Y refers to top-to-bottom direction within the image and Z refers to
the direction across slices (first-to-last image).
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
The Contrasts Window
The Contrasts Window shows a list of all defined contrasts. Contrasts are typically defined
automatically but can be also defined explicitly using a Contrast Definition file. The Contrast
column lists the names of available contrasts. A contrast can be enabled by clicking in the ">"or
"<" column of the respective contrast. Squares with a cross in these columns indicate that the
contrast is enabled while empty squares indicate that the contrast is disabled. These squares act
as toggles, i.e. they can be clicked repeatedly to flip between the enabled and disabled state.
Contrasts are enabled either one-sided or two-sided. If, for example, the ">" but not the "<"
state of the "Houses vs. Faces" contrast is turned on (contrast names are from the example
above), only the voxels exhibiting significantly more activity during the "Faces" condition than
the "Houses" condition will be shown ("Houses > Faces"). If on the other hand the"<" state but
not the ">" state is enabled, voxels will be shown exhibiting significantly more activity during
the "Faces" condition than during the "Houses" condition ("Houses < Faces"). If both are turned
on, the contrast is enabled in a two-sided way ("Houses unequal Faces"). The resulting
statistical map of each enabled contrast is superimposed on the images shown in the various
brain views. It is also possible to specify a conjunction of contrasts by turning on the
Conjunction of contrasts option. If this option is checked, the minimum of t values of all active
contrasts for a voxel is determined and used as the voxel's threshold for the resulting
conjunction map. Note that all included contrasts should be of the same direction (i.e. all ">" or
all "<") when using a conjunction.
If a defined contrast is enabled, all voxels passing the current significance criteria (t threshold)
are shown in the Contrasts Overlay Window. If the Colors Code Contrasts mode is selected (see
Keyboard and Mouse Functions), the significant voxels belonging to a particular contrast are
color-coded in the respective contrast color. The contrast color is shown in the Color column on
the right side of each contrast and correspond to the color of the respective protocol condition
for basic contrasts (e.g., "Faces vs. Baseline").The color of a contrast may be changed by
double-clicking on the contrast color square. This is allowed, however, only after real-time
recording has been completed. The colors of the basic contrasts correspond to the colors of the
main protocol conditions if automatic contrast creation is turned on (default). In order to fully
control the definition of contrasts including their names and colors, a Contrast Definition file
may be specified.
Automatic Creation of Contrasts
There are two levels, "1" and "2" for the automatic creation of contrasts. The level can be
defined in the AutoContrastGenerationLevel spin box in the Statistics tab of the TBV Settings
Dialog. Furthermore, the ContrastFile field must be empty, otherwise the contrasts specified in
that file are used.
If level 1 is specified, contrasts are defined testing each main condition against baseline. It is
assumed that the first condition of the protocol corresponds to the baseline (or "Rest" or
"Fixation") condition. In the example above, three conditions were defined in the protocol,
"Baseline", "Faces" and "Houses". The program thus creates two contrasts testing the two main
conditions against base line ("Faces vs. Baseline" and "Houses vs. Baseline"). In the actual
design matrix created automatically, the first condition (baseline) is not explicitly modeled
although shown in the contrast names. The design matrix contains, however, the constant term
confound predictor, which models the baseline signal level. In summary, the contrasts of level 1
test for the significance of explicitly modeled individual main conditions against baseline (test of
individual beta values for main conditions). A level 1 contrast shown as [-1 +1 0] is actually
tested as [+1 0] in the underlying GLM when showing only the predictors of interest or [+1 0 0]
when adding the confound constant predictor at the third position. The colors of the contrasts
are set to be identical to the colors of the respectively tested main condition from the protocol
definition.
If level 2 is specified (default), all predictors of level 1 are first defined. In addition, contrasts
for comparing all pairs between all main conditions are defined. In the "Baseline", "Faces",
"Houses" example, only one pair needs to be constructed comparing "Houses" vs "Faces" (see
contrast 3 in the example snapshot above). If there would be three main conditions, three
contrasts would be defined ("c2 vs c1", "c3 vs c1" and "c3 vs. c2") together with three level 1
contrasts. The colors for these contrasts are calculated by adding the RGB color definitions of
the individual conditions. In order to specify other contrasts, a Contrast Definition File must be
provided.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
The Information Window
This window on the lower right part of the Turbo-BrainVoyager window shows information about
the current state of analysis. It depicts, for example, whether a single-run or multi-run analysis
is running, whether results are saved to disk or whether previously analyzed data has been
loaded. During real-time analysis, it shows the volume analyzed and the time elapsed from the
start of the analysis. The window also shows the current statistical threshold as well as other
useful information.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
The Specification of Control Parameters
In order to run successfully, Turbo-BrainVoyager needs to know several pieces of information
about the local environment. The most important information is the location of the data, i.e. the
location where the incoming scanned slices are to be expected. In order to find the data, the
program looks in the MasterTBV file, which must be located in the Turbo-BrainVoyager
directory. The "Turbo-BrainVoyager directory" is the folder containing the Turbo-BrainVoyager
executable, i.e. "C:\Program Files\TurboBrainVoyager". You may edit the master file directly or
more conveniently using the MasterTBV File dialog.
The MasterTBV file provides the highest level of control by pointing to a "TBV Watch Directory".
This directory may contain TBV settings files, which provide the next level of control about a
particular run in a particular session. Such a "TBV" file contains information about the names of
the scanned images, the number of slices and the number of time points (functional volumes).
There are also "MTBV settings files", which specify analyses across multiple runs within a
session. You may edit a TBV file directly or more conveniently using the TBV Settings File
dialog.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
The MasterTBV File Dialog
Turbo-BrainVoyager is "bootstrapped" with a MasterTBV file, which must be located in the same
directory as the Turbo-BrainVoyager executable. The master file contains a few global display
settings and it points to the last TBV settings file used.The MasterTBV file is automatically
updated when closing Turbo-BrainVoyager. Individual settings can be edited directly in the text
file or, more conveniently, using the MasterTBV File dialog, which can be invoked using the Edit
MasterTBV File entry in the File menu.
The program looks for a TBV settings file, which provides detailed information about a particular
run in a particular scanning session. A TBV settings file (or "TBV" file for short) might not be
available initially. If running within the IFIS system, the TBV files are generated automatically
when the next functional measurement is prepared on the scanner console. If the program is not
running within the IFIS system, the TBV file may be generated using the TBV Settings dialog, by
editing the file directly or by using custom code to generate it automatically. TurboBrainVoyager constantly "watches" the folder specified in the TBV directory (called
TBVSettingsDirectory in the file) to see wether a valid TBV file is available. This watch folder
can be changed in the dialog by using the Browse button next to the TBV directory (watch
folder) text or by editing the file directly. You may also directly specify a TBV settings file by
using the Browse button next to the TBV file text. The name of the specified TBV file represents
a pattern of file names the program is looking for. The file extension of a TBV file must be
".tbv". The file name is arbitrary but it should end with a (run) number preceded by a minus
sign according to the scheme: "<name>-<nr>". In the example shown above, <name>
corresponds to "NK_FFA_PPA_TAL" and <nr> corresponds to "1". Turbo-BrainVoyager watches
the TBV directory for all TBV files with the specified <name> part and any positive integral
number <n>. This number is also called the "run number" and allows to browse and view
already recorded data. In a typical scenario, an experimental session consists of several runs,
which can be inspected after recording using the Forward and Backward main control buttons. If
a new run is recorded, e.g. run 2, the respective TBV file (e.g. "<name>-2.tbv") should be
located in the same folder. With a click of the Forward button, this file would become the new
current settings file. The program checks whether a run has been already analyzed by looking
for a saved FMR project file. If such a file is available for a specific TBV settings file, the data is
simply reloaded after clicking the Forward or Backward button including statistical maps and
regions-of-interest. If a FMR file with the name provided in the TBV settings file is not found, the
program switches in real-time mode looking for incoming data to be processed.
The Automatically advance to new run option (AutoAdvanceRun entry in text file) specifies
whether the program should switch to a newly available TBV file with a higher run number as
soon as it becomes available. The Automatically start current TBV file option (AutoStartTBV
entry in text file) specifies whether the current TBV settings file is executed immediately (value
"1") or whether the user has first to click the Record button (value "0").
The two options Left and Top in the TBV screen position field can be used to position the
program window at a certain fixed offset with respect to the left upper screen position. In the
text file, these two options correspond to the entries HorizontalWindowPosition and
VerticalWindowPosition. Using the Centered option (recommended) instead of fixed values will
automatically center the program window on the screen.
The main window of the Mac OS X version of Turbo-BrainVoyager can be freely resized. The
Windows and Linux versions, however, use two fixed screen sizes, which can be selected with
the 1280 x 1024 and 1024 x 768 options in the Window size field. In the text file, these two
sizes are coded in the WindowSize entry, which can be either "1" (1024 x 768 pixels) or "2"
(1280 x 1024 pixels). You may also switch between the two sizes using the "Restore" icon in the
right upper corner.
NOTE: The program also looks for files with the ".mtbv" extension. These files specify multi-run
analyses.
NOTE: A MasterTBV file as well as a TBV settings file may contain comments: All characters of
a text line following (and including) the ";" character are ignored.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
The TBV Settings Dialog
A TBV settings file ("<name>.tbv") contains all relevant information to analyze incoming
functional data, including information about the scanner, data points, number of slices and
matrix size. If coupled to the IFIS system, a settings file is provided automatically, otherwise
you have to fill in the necessary values. The "TBV File" dialog provides a convenient and save
way to inspect, create or modify TBV files. Using an external text editor, you can also modify a
TBV file directly. It is, however, recommended to use the "TBV File" dialog because it ensures
that syntactically correct TBV files are created when clicking the "Save" or "Save as..." button.
To open the "TBV File" dialog, click the "Edit TBV file..." item in the "Files" menu. You will see
several tabs describing various subsections of the TBV file. To get a short tool tip explanation of
an entry, locate the mouse cursor over a field without moving the mouse for a short time. To
get more extensive information for each item, click the question mark on the right side of the
dialog's title bar and then click on an item. You can also find a description of each field in the
section TBV settings file.
You will notice that the fields are filled with a background color. The purpose of these colors is
to help you focus on the important information. The colors are defined as follows:
Red color: These entries must be correct to ensure proper real-time processing. Check the red
values and modify them if necessary. As an example, the "WatchFolder", which is the directory
where the real-time data arrives, must be specified correctly to ensure successful data analysis.
Green color: These entries may be changed but they are not critical for proper real-time
processing. Change these options to adapt the analysis and the display to your needs. As an
example, you can chose to run 3D motion correction or not.
Blue color: These entries should normally not be changed. They reflect either important
information which is automatically specified (i.e. by reading header information from the data
files) or they reflect entries which are not (yet) used by the program.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
Settings for Siemens Data
Since software release VB15A, Siemens supports the real-time export of Dicom mosaic images
(one file per functional volume). The recommended way by Siemens to turn this functionality on
is to use the IDEA command tool after switching in advanced user mode on the console
computer (see documentation by Siemens). Unfortunately there seems to be a problem since
the IDEA command tool does not save the specified settings properly to disk. As an alternative
solution, the respective "config" file "C:\MedCom\config\Ice\IceConfig.evp" may be changed
manually, or better, by using the "XBuilder" program that can be started using the Windows
"Run" tool. In XBuilder, change the three export parameters "OnlineTargetPort" (to "-1"),
"OnlineTargetHostName" (to name or I P of PC in network receiving data) and
"OnlineTargetPath" (to the name of the folder of the PC in the network, e.g. "D:\rtfmri"). Note
that the config file is overwritten each time a new patient is registered, i.e. the settings have to
be repeated each time you want to use the real-time export for a new subject.
In order to prepare a TBV file to handle the exported Siemens data, you must change the
settings in the Data Format tab of the TBV Settings dialog. The DataType box must contain the
"SIEMENS_DICOM_MOSAIC" selection. You must also fill in the name of the (expected) first file
of the functional data, which is similar to "001_000004_000001.dcm" (set as default). The first
part "001" is constant throughout all measurements of a subject including the anatomical "scout"
measurements (it is only changed if the same subject is registered in a future session). The
second number is the "series" (or "scan") number. The functional data set is series "4"
("000004") and the value "4" must also be set in the "DicomExpectedSerieseNr" field. The third
number is usually "1" ("000001") and that number should be set in the "DicomFirstVolumeNr"
field (default). This number will change from volume to volume, e.g.
"001_000004_000001.dcm", "001_000004_000002.dcm", "001_000004_000003.dcm" and so on.
In order that TBV separates the different numbers correctly from the first file name, the
"DicomNameDelimiter" must be set to the underscore ("_") symbol (default). Note that one
usually needs to change only the "DicomExpectedSerieseNr" (scan) number for the next
expected run ("4" in our case) since the other entries should normally not change and are set to
correct values as default. If one would, for example, run a second functional run, one should
change "4" into "5" in the "Series" field (and in the "FirstFileName" field, but this is not strictly
necessary).
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
Settings for Philips Data
With the "DRIN" export system, Philips provides a possibility for real-time export. The volumes of
a functional scan are stored incrementally as a series of Analyze files (e.g. "DRIN-00001.img",
"DRIN-00002.img", and so on). All data of one run is stored in a folder (e.g. "0001" for the first
functional run of a session, folder "0002" for the second run and so on).
In order to prepare a TBV file to handle the exported Philips data, you must change the settings
in the Data Format tab of the TBV Settings dialog. The DataType box must contain the
"PHILIPS_ANALYZE_DRIN" selection (see snapshot above). You must also fill in the name of
the (expected) first file of the functional data, which is similar to "<initial_part_00001.img". To be
sure to have the correct folder and file name, you may want to use the Browse button to select
that file as soon as it is available after starting the next real-time run. Turbo-BrainVoyager will
then be started slightly later than the scanner but it will quickly catch up to the most recent time
point. When using the current DRIN data, the slices appear flipped along the anterior-posterior
axis. To correct this, the two options Rotate to swap AP axis and Flip AP axis are available. The
difference of the two options is that they change (flip option, default) or do not change (rotate)
option the left-right convention. The rotate option keeps the original left-right convention (which
seems to be neurological, i.e. left-is-left) while the flip option changes the convention to
radiological convention (left-is-right). This option is used as default since TBV visualizes the data
in radiological convention as indicated by the "L", "R" labels (if shown). Note that this setting is
also important with respect to matching functional data to intra-session anatomical data (see
Preparing Advanced Visualization section). Further note that TBV does not guarantee to get the
left-right convention set correctly and it is advised that one checks the correctness at a given
scanner site (e.g. by attaching markers to one side of the head or by comparing functional images
in TBV with the ones displayed on the Philips console).
Advanced option. Turbo-BrainVoyager can automatically find the current folder by not providing
a file name but a folder with a special extension. In that case the folder is interpreted as a place
holder for a series number and the highest series is selected within the parent folder when realtime analysis is started. To use the automatic folder selection, the "WatchFolder" entry should
have a value like "C:/TBVData/Philips/MyExperiment/<n>". The "<n>" substring will be replaced
by the folder with the highest series number. Note that this folder must already exist when starting
analysis (i.e. when clicking the red GO button), so it is best to start the scanner before starting
TBV.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
Settings for GE Signa HDxt Data
The Signa HDxt generation of GE scanners exports incrementally functional data that is suited
for real-time processing. The exported data is organized at three hierarchical levels. At the
highest level one directory per subject is created with a name like "p1234567"; this "person"
folder will contain all data scanned for a specific subject. Within this folder, each separate
scanning session (in most cases one) is stored in an exam folder with a name like "e1234568".
Within this folder, separate scans (e.g. localizer, structural, functional, diffusion-weighted) are
stored in series folders with names like "s1234569". The data is stored slice-by-slice (not in
volume containers) so many individual files will be produced with names such as "[continous
number].MRDC.[in-series-image-number]".
To use the exported data, select the GE_HDXT_DICOM format in the DataType selection box in
the Data Format tab of the TBV Settings dialog and follow the instructions in the Data type
specific fields text box (see snapshot above). It describes as option 1 to speciy a series folder
that receives the exported data as the WatchFolder in the Folders tab. As the "note" points out,
you need to start scanning the functional series before you can select the correct "s" folder
since it is created only when the first images become available. In option 2, it is sufficient to
select the subject's exam ("e") folder and Turbo-BrainVoyager will figure out automatically
always the latest series folder. Note, however that one should start TBV just after starting the
scan since TBV otherwise would eventually select the previous folder and not the newly creaated
one. TBV checks for the series folder with the highest number right after clicking the red Record
button.
The TBV settings (matrix size and number of slices) must fit the analyzed functional data. The
values slice thickness, gap thickness and field-of-view will be retrieved from the DICOM header
and need not to be specified. The matrix size is also retrieved from the header and compared
with the entered matrix size. The only really critical value in the Data Format tab is the correct
input of the NrOfSlices value.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
MasterTBV Files
Turbo-BrainVoyager is "bootstrapped" with a MasterTBV file, which must be located in the same
directory as the Turbo-BrainVoyager executable. The master file contains a few global display
settings and it points to the last TBV settings file used. A typical MasterTBV file looks like this:
------------------------------------------------------FileVersion:
2
TBVSettingsDirectory:
"C:/TBV_RM_DATA/NicKil/"
TBVSettingsFile:
"NK_FFA_PPA_TAL-1.tbv"
AutoAdvanceRun:
0
AutoStartTBV:
0
WindowSize:
2
HorizontalWindowPosition: Centered
VerticalWindowPosition:
Centered
-------------------------------------------------------
The MasterTBV file is automatically updated when closing Turbo-BrainVoyager. Individual
settings can be edited directly in the text file or, more conveniently, using the MasterTBV File
dialog.
The FileVersion entry is only accessible in the file and must have value "2". The program looks
for a TBV settings file, which provides detailed information about a particular run in a particular
scanning session. A TBV settings file (or "TBV" file for short) might not be available initially. If
running within the IFIS system, the TBV files are generated automatically when the next
functional measurement is prepared on the scanner console. If the program is not running within
the IFIS system, the TBV file may be generated using the TBV Settings dialog, by editing the file
directly or by using custom code to generate it automatically. Turbo-BrainVoyager constantly
"watches" the folder specified in the TBVSettingsDirectory to see wether a valid TBV file is
available. The name of the specified TBV file represents a pattern of file names the program is
looking for. The file extension of a TBV file must be ".tbv". The file name is arbitrary but it
should end with a (run) number preceded by a minus sign according to the scheme: "<name><nr>". In the example shown above, <name> corresponds to "NK_FFA_PPA_TAL" and <nr>
corresponds to "1". Turbo-BrainVoyager watches the TBV directory for all TBV files with the
specified <name> part and any positive integral number <n>. This number is also called the
"run number" and allows to browse and view already recorded data. In a typical scenario, an
experimental session consists of several runs, which can be inspected after recording using the
Forward and Backward main control buttons. If a new run is recorded, e.g. run 2, the respective
TBV file (e.g. "<name>-2.tbv") should be located in the same folder. With a click of the Forward
button, this file would become the new current settings file. The program checks whether a run
has been already analyzed by looking for a saved FMR project file. If such a file is available for
a specific TBV settings file, the data is simply reloaded after clicking the Forward or Backward
button including statistical maps and regions-of-interest. If a FMR file with the name provided in
the TBV settings file is not found, the program switches in real-time mode looking for incoming
data to be processed.
The AutoAdvanceRun entry specifies whether the program should switch to a newly available
TBV file with a higher run number as soon as it becomes available. The AutoStartTBV entry
specifies whether the current TBV settings file is executed immediately (value "1") or whether
the user has first to click the Record button (value "0").
The two options HorizontalWindowPosition and VerticalWindowPosition can be used to position
the program window at a certain fixed offset with respect to the left upper screen position. If
instead of fixed numbers the text Centered is specified (recommended), the program window
will be centered automatically on the screen.
The main window of the Mac OS X version of Turbo-BrainVoyager can be freely resized. The
Windows and Linux versions, however, use two fixed screen sizes, which can be selected with
the WindowSize entry. A value of "1" specifies a small window size (1024 x 768 pixels) and a
value of "2" specifies a large window size (1280 x 1024 pixels).
NOTE: The program also looks for files with the ".mtbv" extension. These files specify multi-run
analyses.
NOTE: A MasterTBV file as well as a TBV settings file may contain comments: All characters of
a text line following (and including) the ";" character are ignored.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
TBV Settings File
A ".tbv" settings file contains all relevant information to analyze incoming functional data,
including information about the scanner, number of data points (volumes), number of slices and
matrix size. If coupled to the IFIS system, a settings file is provided automatically, otherwise
you have to fill in the necessary values. You can enter values for a TBV file directly in the file
using any text editor. A more convenient and save way is to use the TBV Sttings dialog.
When processing of a run is started, the program reads the specifications in the current ".tbv"
file and processes the incoming information accordingly. The following parameters have to be
defined in the correct order within a TBV file. Note that strings referring to files and/or folders
have to be enclosed within > " < signs, which allows specification of file names containing
blanks.
FileVersion:
3
The file version information is important to keep future versions of the program with potentially
new entries in the file compatible with earlier versions. The current file version is "3".
MergeType:
0
This flag specifies whether the TBV file specifies a single-run (value "0") or a multi-run (value
"1") analysis.
Title:
"NK_FFA_PPA"
Specifies a title for this run, which is shown in the top part of the Turbo-BrainVoyager program
window.
ParadigmHelpFile:
""
Refers to a help file specific for a paradigm/protocol, e.g."C:/Program
Files/IFIS/Help/my_paradigm_help.html". If there is no specific help file, provide an empty
string ("").
IFISFMRIAnalysisTests:
tdat
Not used yet, but this line must be present.
IFISFMRIAnalysisOptions:
tdat
Not used yet, but this line must be present.
RawDataBigEndian:
0
This describes the byte ordering of the data which can be either "1" or "0". A value of "1"
specifies a "Big Endian" byte order and a value of "0" a "Little Endian" byte order. This
information is important for determining whether the incoming data has to be "byte swapped" or
not. Since Turbo-BrainVoyager can run on multiple platforms, it needs to compare the byte
ordering of the data with the byte ordering used on the workstation running the program. If the
byte ordering of the machine running Turbo-BrainVoyager is different from the byte ordering
specified in the "RawDataBigEndian" variable, byte swapping is performed.
ShowGODlgAfterPreparation:
0
When this entry is set to "1" a "GO" dialog appears when real-time preprocessing has been
prepared after pressing the Record button. This allows to better synchronize TBV processing
with the scanner if necessary .
WatchFolder:
"C:/NicKil_PPA_FFA/Ser0004/"
The "WatchFolder:" entry specifies where the incoming data can be accessed for real-time
analysis. Note that the folder must be enclosed by '" signs in order to allow path names
containing blanks (see remark above). Access to the scanner data has to be established for each
site with respect to the local network architecture (i.e. NSF mount, Samba or ftp). It is also
possible to specify more than one watch folder by using the following command instead of the
"WatchFolder:" setting:
WatchFolderList:
"C:/TurboBrainVoyager/WatchFoldersList.txt"
The "WatchFolderList:" entry specifies a text file containing a list of folders to be checked for
incoming data. The specified text file must begin with the number of the subsequently listed
watch folders. An example of a correct watch folder list file is shown next:
-------- WatchFoldersList.txt----------2
S:/realtime/data1/
S:/realtime/data2/
---------------------------------------The next entry specifies the target folder which has to be enclosed in quotes, too, in order to
allow for names containing blanks:
TargetFolder:
"C:/NickKil_PPA_FFA/Output_TAL/"
The target folder sets the default directory in which the program saves the processed data
(output directory). If this folder does not exist, it will be created (if possible) when starting
processing.
DataType:
ANALYZE_NW
The "DataType:" field specifies the type of the data produced by a particular manufacturer's
scanner. Currently supported values are: SIEMENS_IMA (OLD Siemens format, Numaris 3.x),
ANALYZE_NW (new Siemens format, Numaris 4.x; in order to work, this format requires a
specific real-time export software module, contact Brain Innovation for details), ANALYZE_DRIN
(for Philips scanners, for details contact Invivo), PHILIPS_REC/PAR (for Philips postrun "neaar" real-time analysis), GE_I (standard GE format),
GE_STANFORD (special file version, which is (was?) used at Stanford University) and DICOM.
Since most scanners save there data in DICOM format, this format is also supported. Note,
however, that due to complex naming patterns of DICOM files, we support this format only for
analysis after a functional run (post-run, near real-time analysis). You may use the "Rename
DICOM" tool in the "File" menu to produce file names, which can be read by TurboBrainVoyager. The program also supports SIEMENS_DICOM_MOSAIC files (post-run) if each
mosaic file contains one functional volume. For post-run analysis, the PHILIPS_REC format (for
Philips scanners) is also supported.
BEGIN: DATA TYPE SPECIFIC ENTRIES
The next entries specifies the necessary information to look for the first file of the current
functional run. With this information, the program can predict also subsequent file names
containing further scans. The respective entries depend on the value of the "DataType:" entry.
For the SIEMENS_IMA data type, the following three entries have to be specified as shown next:
SiemensPatientID:
513
SiemensFirstStudyNr:
2
SiemensFirstImageNr:
4
From this information, a Siemens ".IMA" file can be constructed as "513-2-4.ima" which would
be the first file, Turbo-BrainVoyager would look for.
For the GE_I data type, the following two entries have to be specified:
GESeriesNr:
3
GEFirstImageNr:
26
With the series number ("GESeriesNr") and the first image number ("GEFirstImageNr") together
with the value of the "WatchFolder"), the program can predict the exact file name and location
of the expected data. As soon as that data arrives, it starts processing.
For the GE_STANFORD data type, the following two entries have to be specified:
PFileHeader:
"E06027S003P14848.7"
SliceTimeLooping:
1
The "PFileHeader:" refers to a header file containing all the information necessary to locate and
read this data type. This format works only post-run, near real-time, since the whole data of
run resides in a single file. The ordering of the data in the file can be "slices -> time points" or
"time points ->slices". This can be controlled with the "SliceTimeLooping" parameter.
For the ANALYZE_NW data type, the following entry has to be specified:
FirstFileName:
"Analyze00001.img"
This entry specifies the full name of the first file to process. The software splits the number (in
the example "1") from the file name and then incrementally predicts the names of the
succeeding files (i.e. "Analyze00002.img", "Analyze00003.img" etc.). Each Analyze file contains
one volume (once all slices) of the time series.
For the ANALYZE_DRIN data type, the following entry has to be specified:
FirstFileName:
"1.00001.img"
This entry specifies the full name of the first file to process. The software splits the number (in
the example "1") from the file name and then incrementally predicts the names of the
succeeding files (i.e. "1.00002.img", "1.00003.img" etc.). Each Analyze file contains one volume
(once all slices) of the time series. The left part of the file name (here "1.") must be constant
during one functional run and normally reflects the number of a run within a session (series
number). This allows to place multiple runs within the same directory.
For the PHILIPS_REC data type, the following entry has to be specified:
FirstFileName:
"data.rec"
This entry specifies the full name of the REC file containing all the data of a run.
For the DICOM and SIEMENS_DICOM_MOSAIC data types, the following entries have to be
specified:
FirstFileName:
"subj-0014-0001-0001.dcm"
DicomNameDelimiter:
"-"
DicomNameExtension:
"dcm"
DicomFirstVolumeNr:
1
DicomFirstImageNr:
1
The first file name specifies the first file from which to read the data, which can be a single
slice (DICOM format) or a mosaic file (SIEMENS_DICOM_MOSAIC). In the latter case, the mosaic
file contains all slices of the first volume arranged in a "mosaic picture". The
"DicomNameDelimiter:" and "DicomNameExtension:" fields describe the naming scheme of the
Dicom files. When using the "Rename Dicom" tool of Turbo-BrainVoyager, the files will be
labelled as "<fixed_name>-<series_nr>-<volume_nr>-<image_nr>.dcm". If you do not use the
"Rename Dicom" tool, describe the delimiter and extension. Note that the program can only
read files, which have a fixed left string and follow the logic
"<fixed_name><delimiter><volume_nr><delimiter><image_nr>.<extension>". Although the
program can extract the volume and image number from the provided first file name, you must
provide these values in the "DicomFirstVolumeNr:" and "DicomFirstImageNr:" entries.
For most data formats (PHILIPS_REC, ANALYZE_DRIN, ANALYZE_NW, DICOM,
SIEMENS_DICOM_MOSAIC), the following fields must be specified next:
InplaneFoVX:
224
InplaneFoVY:
224
SliceThickness:
3.0
GapThickness:
1.0
These values are important for defining the resolution (voxel size) of the data. Knowing the
voxel size is important for proper visualization in the orthographic view and for correct
computation during motion correction. The "InplaneFoVX:" and "InplaneFoVY:" values describe
the size of the imaged rectangular region (slice), measured in millimeter. If these values are
divided by the dimensions of an image (see "MatrixSizeX:" and "MatrixSizeY:" below), the size
of a voxel is determined for two (inplane) dimensions. The "SliceThickness:" value directly
defines the size of a voxel in the third dimension (in mm). The "GapThickness:" value completes
the information by specifying whether a gap has been left between the slices.
END: DATA TYPE SPECIFIC ENTRIES
After the format specific entries, the following entries must follow for all formats.
TimeOutSeconds:
10
This entry specifies how long the program maximally waits for an expected file name. If the
expected file does not arrive in the watch folder(s) within the specified number of seconds, the
program stops reporting a "TIME OUT ERROR".
MatrixSizeX:
64
MatrixSizeY:
64
These two values specify the dimensions of an individual slice. EPI images typically contain 64 x
64 pixels.
Only for the SIEMENS_DICOM_MOSAIC format, the following two entries have to follow:
MosaicResolutionX:
384
MosaicResolutionY:
384
In this data format, the individual slices comprising one volume are packed in a "mosaic"
image. The ordering of pixel data within a mosaic image has to be sorted out by the program to
get individual slices. The two values "MosaicResolutionX:" and " MosaicResolutionY:" specify the
resolution of one mosaic image. With the example values "384" x "384", a maximum of 6 x 6 =
36 images with a resolution of 64 x 64 are located in one file.
Only for the SIEMENS_IMA format, the following two entries have to follow:
SiemensMosaicSequence:
1
SiemensMosaicResolution:
256
SiemensFixedRunNumber:
0
If the "SiemensMosaicSequence:" entry is set to "1", the individual slices comprising one volume
are packed in a "mosaic" image. The ordering of pixel data within a mosaic image has to be
sorted out by the program. The resolution of one mosaic image is specified in the
"SiemensMosaicResolution:" entry, which is "256"in our example. In one such file (256 x 256) 16
slices of a resolution of 64 x 64 are stored. If more than 16 slices comprise one functional
volume, the remaining slices are typically stored in a second mosaic file. Thie
"SiemensFixedRunNumber:" entry specifies a particular version of the Siemens file naming
scheme (for more information, see section "Technical details"). Typically, Siemens uses the
scheme <pat_id>-<study_nr>-<image_nr>.ima where <pat_id> is constant throughout a
scanning session and <image_nr> runs continously from the first image scanned up to the last
image of a session. The <study_nr> changes for each study, which can be a scout, a structural
measurement etc. During a functional run, each volume is normally treated as a "study" with
respect to the file naming scheme and is, thus, incremented.. There is now also the possibility
that new Siemens scanners/sequences keep the study number constant throughout a functional
run resembling a "series" number in the GE folder/file naming scheme. The entry
"SiemensFixedRunNumber:" is used to select between these two file naming possibilities.
NrOfVolumes:
110
This entry specifies the number of volumes which are expected to be recorded during the
functional run. In case the sequence is aborted, less volumes might be actually processed.
NrOfVolumesToSkip:
2
This entry specifies the number of volumes which will be skipped at the beginning and, thus, not
included in the statistical analysis. Skipping a few volumes at the beginning is usually performed
to exclude the T1-saturated initial scans leading to very high signal values. T1 weighting drops
quickly and reaches a steady-state after a few volumes. Although TBV does not include the
specified number of to-be-skipped EPI volumes in the statistical analysis, it is reading the very
first volume for display in the Multi-Slice, Single Slice and Volume View. While high T1
weighting is a problem for statistical time series analysis, it is useful for visualization because it
shows structural information (gyri/sulci).
NrOfSlices:
30
This entry specifies the number of slices comprising one functional volume, in this example
"30".
SlicePrefix:
"NK_FFA_PPA-"
ProjectName:
"NK_FFA_PPA"
These two settings are used for saving (processed) data to the specified "TargetFolder" in
BrainVoyager format. The names of all written files are based on the name specified in the
"ProjectName" entry. Most data structures are saved at the end of a functional run but ROI time
course data is saved incrementally and can be used for custom real-time analysis. The program
saves the following files: a FMR project file (e.g. "NK_FFA_PPA.fmr"), as many slice time course
(STC) files as there are slices (e.t. "NK_FFA_PPA-1.stc" ... "NK_FFA_PPA-30.stc"), a stimulation
protocol (PRT) file (e.g. "NK_FFA_PPA.prt") containing also behavioral data if present, a AMR file
(e.g. "NK_FFA_PPA.amr") and VMR file (e.g. "NK_FFA_PPA_EPI.vmr") containing the image
information from the first volume, which is used for display as described above. If 3D motion
correction is enabled, a motion correction log file (i.e. "NK_FFA_PPA_3DMC.log") is saved as
well as a motion correction design matrix file (e.g. "NK_FFA_PPA_3DMC.rtc"). There will be also
a file written containing statistical maps (i.e. "NK_FFA_PPA.mps") and a file containing results
from the performed General LInear Model (e.g. "NK_FFA_PPA.glm"), a contrast file (e.g.
"NK_FFA_PPA.ctr") and a file containing any selected ROIs (e.g. "NK_FFA_PPA.roi") .
TR:
2000
This entry specifies the time between two consecutive measurements of the same slice. It
determines the resolution of the x-axis in the time course, motion correction and behavioral
data plots; in this example, each data point represents 2 seconds of elapsed time.
InterSliceTime:
66
This entry specifies the time gap from one slice to the next within a functional volume. It will be
used in the future for inter-slice timing correction, which is not performed in the current version
of the program.
ROIColorsFile:
"C:/TBV_RM_DATA/NicKil/ROISelectionColors.rcd"
This entry specifies a file defining colors to be used for ROIs. If you want the program to use
default colors, set this entry to an empty string ("").
MultiSliceROISelection:
3
The value of this entry specifies how many slices should be used to define ROIs. If the value is
"1", only voxels of the current slice are used when dragging a ROI or when CTRL-clicking on a
voxel. If the value is larger than "1", slices above and below the current slice are used in
addition to define a ROI.
Threshold:
3
This value specifies the statistical threshold used to "clip" the incrementally computed contrast
maps. It is a t value, which must be equal to or larger than 1.0. The threshold can be changed
during (or after) a functional run, for details see section Keyboard and Mouse functions.
ClusterSizePixels:
3
This value specifies the cluster threshold used to "clip" the statistical maps. A color-coded voxel
is shown, if the map value at this point exceeds 1) the statistical threshold and 2) belongs to a
cluster with at least the number of connected pixels also exceeding the statistical threshold. If a
statistical map value does not reach these two criteria, the "background"
value (EPI, inplane, VMR, SRF) is shown at that location.
NrOfColumns:
6
NrOfRows:
5
These entries specify the layout of the display, i.e. how the slices are arranged in rows and
columns. Since the Brain Window is a square (Windows version), these two values should be the
same in order to get a display with square pixels (assuming that the slice images are also
square, i.e. 64x64). Make sure that the product "NrOfColumns:" x "NrOfRows:" is equal or
larger than the number of scanned slices per volume, otherwise some images will not be shown
in Multi-Slice View.
ForceTRDelay:
1
TBV is normally faster in processing then the time specified in the TR value. Since the data
arrives incrementally during real-time recording, the program tries to read the data until it is
available for processing. If the "ForceTRDelay" entry is set to "1" instead of "0", TBV will wait
until the time of a TR has passed before it attempts to read the data. This might be useful to
avoid reading of data before it is completely written, which seems relevant for some scanners.
This option is also useful if real-time processing is re-run with all data available on disk.
StimulationProtocol:
"C:/TBV_RM_DATA/NicKil/FFA_PPA.prt"
This is a standard BrainVoyager protocol file defining the intervals of conditions used in a
experiment. In a Eloquence/IFIS environment, a "TDatFile" entry must be specified instead of a
protocol. The TDAT fie is incrementally written during real-time anlaysis with detailed
information about the blocks/trials/events occurring within the run, including behavioral data.
For details of the TDAT file, see section "The IFIS TDAT file". A protocol or TDAT file is the basis
for statistical computations since (part of) the design matrix (predictors of interest) is
automatically created from the protocol. Whereas a TDAT file is created automatically by the
Eloquence/IFIS system, you can create a protocol file using the "Stimulation Protocol" dialog.
ContrastFile:
"C:/TBV_RM_DATA/NicKil/FFA_PPA.ctr"
TBV is able to build contrasts automatically (see below) using the condition predictors created
from the protocol. Using a contrast file, desired contrasts may be specified explicitly. To use
automatic contrast definition, set "ContrastFile" to the empty string ("").
AutoContrastGenerationLevel:
2
If no contrast file is specified, TBV generates contrasts automatically. If
"AutoContrastGenerationLevel" is set to "1", one contrast is defined fore each main condition
predictor. If the value is "2", predictors testing all pairs between main conditions are
additionally defined.
DriftConfoundPredictors:
2
This entry may be used to defined confound predictors for the removal of temporal drifts in the
data. If the value is "1", a linear trend confound predictor is added to the design matrix. If the
value is larger than "1", Discrete Cosine Transform (DCT) predictors are added to the design
matrix. A value of "2" is recommended removing low-frequency drifts.
MotionCorrection:
1
This entry specifies whether 3D motion detection and correction should be performed ("1") or
not ("0").
SpatialGaussianSmoothing:
1
SpatialSmoothingFWHM:
4
If "SpatialGaussianSmoothing" is turned on ("1"), each volume is spatially smoothed prior to
incremental statistical analysis using a kernel width in millimeter specified in the
"SpatialSmoothingFWHN" entry.
OverlayInplaneData:
0
If this entry is specified to "1", the program will read slices form an extra scan (T1 or T2
weighted), which will be displayed in the Multi-Slice, Single Slice and Volume View. During realtime analysis, the user can toggle between the EPI slices and the slices from the extra scan
(normally high-resolution anatomical images). The images of the extra scan have to be coplanar
("inplane"), which means that the extra scan must contain the same number of slices with the
same slice positions as the functional scans. Only if this entry is set to "1", the following
information has to be provided (most formats are supported, here demonstrated for DICOM
format):
OverlayInplaneFolder:
"C:/TBV_RM_DATA/NicKil/"
OverlayInplaneDataType:
DICOM
OverlayInplaneFirstFileName:
"NicKil_Coplanar-00001.dcm"
OverlayInplaneMatrixSizeX:
256
OverlayInplaneMatrixSizeY:
256
The entry "OverlayInplaneDataType:" specifies the format of the (high-resolution) inplane extra
scan. This will be in most cases the same or a similar format as used in the "DataType:" field.
Supported formats are DICOM, GE_I, GE_MR, ANALYZE_DRIN, ANALYZE_NW and SIEMENS_IMA.
The "OverlayInplaneFolder:"specifies the folder where the inplane scan has been stored. Note,
that the inplane data must be recorded prior to the functional run. The
"OverlayInplaneFirstFileName:" entry specifes the name of the first file (which may be the only
file for some formats, e.g. ANALYZE). Together with the specifed folder, this information tells
the program where to find the data of the extra scan. The two entries
"OverlayInplaneMatrixSizeX:" and "OverlayInplaneMatrixSizeY:" specify the dimensions of the
inplane images. Note, that these can be higher than the functional (EPI) images; the program
will automatically adjust the different matrix sizes of the functional and inplane scans. Note,
however, that the aspect ration between the dimensions of the functional data and the coplanar
data must be identical.
FlipSliceOrderInMultiSliceView:
1
FlipSliceOrderInVolumeView:
1
These entries specify whether the order of the slices should be reversed. If axial slices are
recorded from inferior to superior, the 3D visualization in the volume view would show the brain
upside down because the first slice encountered is drawn at the top followed by the second slice
and so on. To visualize the brain adequately, set this value to "1" (default). Note: At present
only the second value is used setting the across-slices axis flip for both the multi-slice and the
volume view. Note also that in v2.4 this setting can be set in the TBV Settings file and not in the
TBV Settings dialog.
IntraSessionMotionCorrection:
0
As default, motion correction (if enabled) aligns each incoming volume to the first volume of the
run. With the "IntraSessionMotionCorrection" entry, it is possible to align images to an earlier
run if multiple runs are performd with the same subject in one session using the same slice
position parameters in subsequent runs. If this entry is enabled, the following entry has to be
provided:
IntraSessionMotionCorrectionFile: "NicKil-Motion.fmr"
This entry specifies the previous functional run to which the current run should be aligned.
OverlayOnVMRMode:
3
This entry allows to specify visualization on high-resolution 3D data sets (if value > "0") With a
value of "1', a intra-session 3D data set has to be provided. Slice position information of the
intra-session 3D data set must be provided in a "FMRVMRAlignVMRPosFile", which is generateed
automatically for the "ANALYZE_NW" format. If the value is "2", an AC-PC normalized file is
expectec together with a intrasession to AC-PC spatial transformation file. If the value is "3", a
Talairach normalized file is expected together with an AC-PC transformation file and a Talairach
landmark file as shown in these example entries:
FMRVMRAlignVMRPosFile:
"C:/TBV_RM_DATA/NicKil/NicKil_Ser000X/NicKil_anatomy/Ana0002/Analyze00001.pos"
ACPCTransformationFile:
"C:/TBV_RM_DATA/NicKil/NicKil_I/NK1_INH_ACPC.trf"
TalairachCerebrumBorderFile:
"C:/TBV_RM_DATA/NicKil/NicKil_I/NK1_INH_ACPC.tal"
TalairachVMRFile:
"C:/TBV_RM_DATA/NicKil/NicKil_I/NK1_INH_TAL.vmr"
OverlayOnSRFMode:
2
This entry allows to specify visualizations on surface-rendered cortex meshes (if value > "0"
and "OverlayOnVMRMode > "0"). With a value of "1", one cortex mesh has to be provided. The
mesh must be in the same space as the space used for visualization on a high-resolution 3D
data set. With a value of "2", two cortex meshes, e.g. one for the left and one for the right
hemisphere, have to be provided as shown in the following example entries:
SRFFileLH:
"C:/TBV_RM_DATA/NicKil/NicKil_I/NK_TAL_LH_RECOSM_SPH.srf"
SRFFileRH:
"C:/TBV_RM_DATA/NicKil/NicKil_I/NK_TAL_RH_RECOSM_SPH.srf"
FeedbackTargetFolder:
"C:/TBV_RM_DATA/NickKil/target_TAL/"
This entry needs only to be filled with a valid folder string if the neurofeedback module is used.
If a valid folder is provided, ROI intensity values (graphically) fed back to the subject are sved
incrementally in that folder.
As an example, a complete settings file looks like this:
----------------------------------- NK_FFA_PPA_TAL-1.tbv ---------------------------------------FileVersion:
3
MergeType:
0
Title:
"NK_FFA_PPA"
ParadigmHelpFile:
""
IFISfMRIAnalysisTests:
tdat
IFISfMRIAnalysisOptions:
tdat
RawDataBigEndian:
0
ShowGODlgAfterPreparation:
0
WatchFolder:
"C:/TBV_RM_DATA/NicKil/NicKil_Ser000X/NicKil_PPA_FFA/Ser0004/"
TargetFolder:
"C:/TBV_RM_DATA/NicKil/target_TAL/"
DataType:
ANALYZE_NW
FirstFileName:
"Analyze00001.img"
InplaneFoVX:
224
InplaneFoVY:
224
SliceThickness:
3
GapThickness:
0.99
TimeOutSeconds:
10
MatrixSizeX:
64
MatrixSizeY:
64
NrOfVolumes:
110
NrOfVolumesToSkip:
2
NrOfSlices:
30
SlicePrefix:
"NK_FFA_PPA-"
ProjectName:
"NK_FFA_PPA"
TR:
2000
InterSliceTime:
66
ROIColorsFile:
"C:/TBV_RM_DATA/NicKil/ROISelectionColors.rcd"
MultiSliceROISelection:
3
Threshold:
3
ClusterSizePixels:
4
NrOfColumns:
6
NrOfRows:
5
ForceTRDelay:
1
StimulationProtocol:
"C:/TBV_RM_DATA/NicKil/FFA_PPA.prt"
ContrastFile:
"C:/TBV_RM_DATA/NicKil/FFA_PPA.ctr"
DriftConfoundPredictors:
1
AutoContrastGenerationLevel:
2
MotionCorrection:
1
SpatialGaussianSmoothing:
1
SpatialSmoothingFWHM:
4
OverlayInplaneData:
0
FlipSliceOrderInEPISliceView:
1
FlipSliceOrderInEPIOrthoView:
1
IntraSessionMotionCorrection:
0
OverlayOnVMRMode:
3
FMRVMRAlignVMRPosFile:
"C:/TBV_RM_DATA/NicKil/NicKil_Ser000X/NicKil_anatomy/Ana0002/Analyze00001.pos"
ACPCTransformationFile:
"C:/TBV_RM_DATA/NicKil/NicKil_I/NK1_INH_ACPC.trf"
TalairachCerebrumBorderFile:
"C:/TBV_RM_DATA/NicKil/NicKil_I/NK1_INH_ACPC.tal"
TalairachVMRFile:
"C:/TBV_RM_DATA/NicKil/NicKil_I/NK1_INH_TAL.vmr"
OverlayOnSRFMode:
2
SRFFileLH:
"C:/TBV_RM_DATA/NicKil/NicKil_I/NK_TAL_LH_RECOSM_SPH.srf"
SRFFileRH:
"C:/TBV_RM_DATA/NicKil/NicKil_I/NK_TAL_RH_RECOSM_SPH.srf"
FeedbackTargetFolder:
"C:/TBV_RM_DATA/NickKil/target_TAL/"
--------------------------------------------------------------------------------------------------
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
Contrast Definition Files
While contrasts may be autogenerated by TBV, a Contrast Definition file (file extension ".CTR")
allows for full control over the definition, names and colors of contrasts. The contrast file is
used by TBV if selected in the "ContrastFile" entry in the "Statistics" tab of the TBV settings file.
Alternatively, you may edit the respective entry directly in the settings file.
A contrast definition file (version 3) starts with a series of entries (see below). The most
important general settings are "NrOfContrasts" specifying the number of defined contrasts and
"NrOfValues" specifying the number of entries per contrast. This value must match the number
of conditions in the used stimulation protocol if the "BaselineInContrasts" entry is set to "1" and
if the protocl contains a baseline condition. If the "BaselineInContrasts" entry is set to "1"
(recommended), the contrasts must contain an entry for the baseline at the first position
(internally the baseline condition is not explicitly modeled in the design matrix, this is only
relevant for display). In the context of automatic generation of contrasts it is strictly necessary
that a baseline condition is contained in the protocol, which must be defined before other
conditions (i.e. at position 1). When specifying contrasts with a contrast file, the
"BaselinePosInProtocol" entry may be used to specify which condition corresponds to the
baseline condition. By setting this value to "0", it is even possible to use protocols that do not
contain an explicit baseline condition (this is often the case in event-related designs).
After these "header" definitions, four sections describe individual contrasts in detail. The
"ContrastNames" section defines the names of the contrasts (here 3). The names may be any
string and must be enclosed in quote signs ("); they appear as specified in the Contrast Window.
The names in the example contain both the actual vector definition (see below) as well as with
actual condition names. The actual definition of the contrast vectors used for internal
calculations follows in the "ContrastVectors" section. Each row corresponds to one contrast. In
our example (see below), the baseline condition appears in the contrasts at the first position
(e.g., "-1" in the first two contrasts and "0" in the third contrast). The two first contrasts below
actually test for the significance of individual beta values of the model (bFaces, bHouses) since
the baseline condition is not explicitly modeled, while the last contrast compares the beta values
of the two main conditions, "Faces" and "Houses". The next section determines whether a
contrast is selected initially or not. A value of "0" indicates that the respective contrast should
not be shown when starting real-time analysis; it can be, however enabled any time by clicking
in the Contrast Window. A value of "1" indicates that the contrast is enabled in a one-sided
manner, i.e. only positive t values surpassing the threshold will be shown (">" contrast). A
value of "2" indicates that the contrast is enabled one-sided showing only negative t values
surpassing the theshold ("<" contrast). A value of "3" indicates a two-sided contrast, i.e.voxels
surpoassing either the positive or negative threshold will be shown. The last section
("ContrastColors") contains the definition of the colors of the contrasts in RGB values. In the
example, the first contrast is colored in red and the second in green matching the respective
colors of the protocol; the third contrast, comparing the two main conditions, is colored in blue.
Here is an example of a contrast definition file for a protocol with one baseline and two main
conditions:
<---------- FFA_PPA.ctr ---------->
FileVersion:
3
NrOfContrasts:
3
NrOfValues:
3
BaselineInContrasts:
1
BaselinePosInProtocol: 1
ContrastNames:
"[-1 +1 0] Faces vs. Baseline"
"[-1 0 +1] Houses vs. Baseline"
"[ 0 -1 +1] Houses vs. Faces"
ContrastVectors:
-1 1 0
-1 0 1
0 -1 1
InitialSelectionState:
0
1
3
ContrastColors:
255 0 0
0 255 0
0 0 255
<---------- FFA_PPA.ctr ---------->
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
Real-Time Protocols
In case that one know already the experimental protocol in advance of functional scanning, the
easiest way to specify the protocol is to use (or prepare if not already available) a standard
(Turbo-)BrainVoyager protocol (PRT) file. There are, however, interesting and challenging
experimental ideas, which would benefit from a dynamic creation of the protocol (and
consequently design matrix). The RTP file format has been specified to allow the incremental
build-up of the protocol during an ongoing measurement.
The real-time protocol (RTP) file format expects a short headerspecifying important general
information including the time resolution used to specify events/blocks, number of experimental
conditions, contrasts (optionally) as well asentries specifying colors for plotting time courses in
TBV. After the header, anRTP file provides incrementally information about the experimental
protocol, i.e.moments in time when conditions introduced in the header are turned on and
off.While obtaining the image data, Turbo-BrainVoyager (TBV) reads the incrementallysupplied
information and builds a design matrix on the fly for statisticalanalysis.
At the begin of a scanning, the RTP file must be available containing the header information. The
header is read only once when real-time analysis is startedand must not change during the
analysis. The lines following the header containthe main information specifyng the on/off state
of experimental conditions.Note that the RTP file may not be rewritten each time when new
protocol information ismade available, but the new information must be appended to the RTPfile
as time progresses. At each time point (TR, volume), TBV checks whetherthere is new
information appended to the file and updates the protocol and designmatrix (including HRF
application) accordingly. TBV keeps a pointer at the current position of theopened file to avoid
rereading and parsing of the whole file repeatedly.This is the reason why the incremental
protocol information must beappended to the real-time protocol file. More specifically, for each
new piece of information, software writing theRTP file should open the file in "append" mode,
then write the new pieceof information (e.g. one line of the protocol), and then close the file.
After the header, condition state lines (CSLs) specifythe state of the experimental protocol. Each
CSL characterizes a change inthe protocol state at a certain time point; as long as the current
conditionstate does not change, it is not necessary to provide condition state lines.It is
nonetheless possible to specify more lines than necessary, e.g. itmight be convenient for
custom software to write a CSL at every TR (volumetime point) even if the condition state does
not change.
Each condition state line begins with a time marker in units defined in the
"ResolutionOfTime"parameter in the header (volumes or milliseconds). The entries in a CSL
following the time markercode the state (1 = on / 0 = off) of each condition included in
thedesign matrix. Note: Since entries are interpreted as float value, you may alsocode condition
state values such as 0.7, e.g. for parametric designs.A baseline condition (e.g. "rest", "fixation")
may be specified but shouldnot be included in the design matrix. You can use the "Modelled"
entry (values "yes" or "no") in theheader to exclude a condition from the design matrix. If the
"ResolutionOfTime"parameter is specified as "Volumes", counting starts with value "1", i.e.
thefirst volume is "1" (not "0"). Specifying time in volumes(time points) has the advantage that
the protocol header needs notbe changed for subsequent scans if the TR value changes (in TBV
settings file).If "ResolutionOfTime" is specifeid as "ms", time starts at "0". TBV uses the
following equation to convert a volume specification into a millisecondspecification: ms =
(volume - 1) * TR (or vice versa: volume = ms/TR + 1).
Note that protocol time starts not necessarily with the first data available fromthe scanner. If
the "SkipVolumes" entry in the TBV settings file is larger than "0", the respective number of
initial volumes (time points) are skipped from analysis. If a run consists, for example, of 100
time points (volumes) and 2 volumes are skipped, the first two volumes would not be used in
TBVfor data analysis and the third scanned volume would correspond to the first volume of the
protocol.Why would one skip volumes for analysis? Skipping a few initial volumes is useful in
order to exclude the first functional volumes possessing high intensity values due to T1saturation; if these volumes would beincluded, high signal values would detoriate the analysis
and displayof time courses. Note that TBV still reads the very first available volumeand uses it
for display of the functional data because thefirst T1 saturated volume provides good anatomical
detail as opposed to the functional images in later volumes. Note that some scanners perform a
few "implicit" ("prep" or preparatory) scans before saving data to disk; in that case skipping of
volumes is not necessary. While this situation does not require skipping of volumes making
specification of protocols easier, the T1 saturated first volume is no longer available for
visualization.
RTP Header
FileVersion:
[(int)]
' value "1" at present
ResolutionOfTime:
[volumes | ms]
ApplyHRF:
[yes | no]
' apply HRF function, "yes" recommended
NrOfConditions:
[(int)]
' number of conditions
' For each condition, one line:
[Condition name: "name"] [ColorRGB: (int) (int) (int)] [Modelled: yes | no]
' The condition name must be enclosed in " symbols allowing strings containing blanks
' The RGB values must be in range 0 - 255
' The "Modelled" entry allows to drop conditions from the design matrix.
' It is recommended to only drop the baseline condition (if specified)
' If no condition is dropped, baseline is assumed to be those intervals
' during which no condition is "on"
NrOfContrasts:
[TBV | Auto1 | Auto2 | (int)]
' If "TBV" is specified, the contrast specification in TBV settings file is used.
' if "Auto1" is specified, contrasts are created automatically testing
' each main condition with respect to baseline
' if "Auto2" is specified, contrasts are created as with "Auto1". In addititon,
' contrasts are generated comparing all possible comparisons between pairs of main conditions
' If a number is provided, lines must be specified to code each desired contrast.
' First the "ContrastNames:" field must contain one row per contrast specifying
' the contrast name enclosed in quote signs.
' Then the "ContrastVectors:" field must follow with one line per contrast. A contrast
' weight value must be specified for each condition including non-modelled conditions.
' Then the "InitialSelections:" field contains one value per line indicating whether
' the respective contrast should be turned on as default in TBV. A value of "0"
' turns off the contrast, a vlaue of "1" turns it on in the direction "greater than",
' a value of "2" turns the contrast on in the direction "smaller than", and a value
' of "3" turns both directions on (resulting in positive and negative colors) for
' the respective contrast.
' Finally the "ContrastColors:" entry contains per line the color of the respective
' contrast with three values coding the red, green and blue channel in a range
' from 0 - 255.
' The next 4 entries are not relevnt for analysis but are
' only used for time course display purposes
BackgroundColor:
[ColorRGB: (int) (int) (int)]
TextColor:
[ColorRGB: (int) (int) (int)]
TimeCourseColor:
[ColorRGB: (int) (int) (int)]
TimeCourseThick:
[(int)]
RTP Data
SCAN BEGIN ' this entry marks the begin of the incremental protocol time data
' condition state lines - CSLs (for explanations, see above)
[Time-1: (int)] [StateOfCondition-1: 0 | 1] [StateOfCondition-2: 0 | 1] ...
[Time-2: (int)] [StateOfCondition-1: 0 | 1] [StateOfCondition-2: 0 | 1] ...
:
:
SCAN END
' TBV will stop processing if this symbol encountered or if "time" > "expected time" (NrOfVolumes x TR)
Sample RTP File 1
Assuming short measurement with 32 volumes
FileVersion:
1
ResolutionOfTime:
volumes
ApplyHRF:
yes
NrOfConditions: 3
"Baseline"
128 128 128
No
' baseline not modelled in DM, thus two conditions specified in CSLs
"Faces"
255
0
0
Yes
"Houses"
0 255
0
Yes
NrofContrasts: 3 ' The same contrasts specified in "ContrastVectors" would be generated if "Auto2" would be used
ContrastNames:
"[-1 +1 0] Faces vs. Baseline"
"[-1 0 +1] Houses vs. Baseline"
"[ 0 -1 +1] Houses vs. Faces"
ContrastVectors:
-1 +1 0
-1 0 +1
0 -1 +1
InitialSelectionState:
1
1
3
ContrastColors:
255
0
0
0 255
0
0 200 255
BackgroundColor:
TextColor:
TimeCourseColor:
TimeCourseThick:
0
0
0
255 255 255
255 255 255
2
SCAN BEGIN
1
0 0 ' column 1: time marker, column 2: "Neutral Faces", column 3: "Emotional Faces"
9
1 0
15 0 0
21 0 1
27 0 0
SCAN END
Sample RTP File 2
The same protocol information could be also provided by specifying a CSL at each volume
FileVersion:
1
ResolutionOfTime:
volumes
ApplyHRF:
yes
NrOfConditions: 3
"Baseline"
128 128 128
No
"Faces"
255
0
0
Yes
"Houses"
0 255
0
Yes
NrofContrasts: 3
ContrastNames:
"[-1 +1 0] Faces vs. Baseline"
"[-1 0 +1] Houses vs. Baseline"
"[ 0 -1 +1] Houses vs. Faces"
ContrastVectors:
-1 +1 0
-1 0 +1
0 -1 +1
InitialSelectionState:
1
1
3
ContrastColors:
255
0
0
0 255
0
0 200 255
BackgroundColor:
0
0
0
TextColor:
255 255 255
TimeCourseColor:
255 255 30
TimeCourseThick:
2
SCAN BEGIN
1
0 0
2
0 0
3
0 0
4
0 0
5
0 0
6
0 0
7
0 0
8
0 0
9
1 0
10 1 0
11 1 0
12 1 0
13 1 0
14 1 0
15 0 0
16 0 0
17 0 0
18 0 0
19 0 0
20 0 0
21 0 1
22 0 1
23 0 1
24 0 1
25 0 1
26 0 1
27 0 0
28 0 0
29 0 0
30 0 0
31 0 0
32 0 0
SCAN END
Sample RTP File 3
Assuming a TR of 2000 ms, the same information could be also provided in millisecond
resolution (ResolutionOfTime: ms)
FileVersion:
1
ResolutionOfTime:
ms
ApplyHRF:
yes
NrOfConditions: 3
"Baseline"
128 128 128
No
"Faces"
255
0
0
Yes
"Houses"
0 255
0
Yes
NrofContrasts: 3
ContrastNames:
"[-1 +1 0] Faces vs. Baseline"
"[-1 0 +1] Houses vs. Baseline"
"[ 0 -1 +1] Houses vs. Faces"
ContrastVectors:
-1 +1 0
-1 0 +1
0 -1 +1
InitialSelectionState:
1
1
3
ContrastColors:
255
0
0
0 255
0
0 200 255
BackgroundColor:
0
0
0
TextColor:
255 255 255
TimeCourseColor:
255 255 30
TimeCourseThick:
2
SCAN BEGIN
0
0 0
16000 1 0
28000 0 0
40000 0 1
52000 0 0
SCAN END
The same information could be also specified by providing a CSL at each volume (or even at
arbitrary time points)
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
The Neurofeedback Dialog
The Neurofeedback dialog allows to select the data from one or more ROIs as the source of
feedback information for a subject during an ongoing measurement. It constitutes a simple Brain
Computer Interface (BCI) allowing to use different display formats for neurofeedback. The signal
from a ROI can be presented in two major formats to the subject, either in thermometer display
(also called bar display, see above) or in time course display (see below) type. These types can
be selected in the Feedback type field by selecting the Activation level bar or Time course plot
option, respectively. (the "Pong" options are for special applications not described here). The
"Delayed feedback" option allows to calculate a mean feedback signal that can be used for
custon feedback displays, i.e. at the end of modulation blocks.
Output formats. From the dialog, only the content of the plot window on the left side is used
for neurofeedback presentation. At each volume, its current content is saved as a bitmap (.PNG
file) to disk in the neurofeedback target folder specified in the TBV Settings dialog,
corresponding as default to the general target (output) folder. In an experiment named
"S3_FFA_Feedback", the files incrementally saved in the target folder would be called
"S3_FFA_Feedback-1.png", "S3_FFA_Feedback-2.png" for data points (volumes) "1", "2" and so
on. These files can be picked up by custom software for final display to the subject. If you are
interested, you can use the Neurofeedback Presenter software for presentation to the subject,
which you can request by sending an email to support_at_brainvoyager_dot_com. The creation
of bitmaps for neurofeedback can be turned off by checking the No output to subject option
Besides the image output, the Neurofeedback dialog also saves the current signal values within
each ROI to disk in a "ROI Time Points" (.RTP) file. NOTE: Since TBV v2.8, saving of RTP files is
turned on and off in the Analysis menu. If turned on (default), and in case of an experiment
named "S3_FFA_Feedback", you would find the files "S3_FFA_Feedback-1.rtp",
"S3_FFA_Feedback-2.rtp" and so on arriving sequentially in the target folder, i.e. one file for
each time point. Each file contains one line of information containing as the first entry the
number of ROIs, then a list of the raw signal values for each ROI and finally a numerical value
indicating the protocol condition at that time point. In the case of two ROIs, for example, a
typical ".rtp" file would look like this: "2 698.782 685.294 1"; here the first ROI has an average
value of 698.782 and the second ROI a value of 685.294 at the respective time point; the last
value indicates that at this time point, condition "1" was active.
Additional real-time information for custom processing is stored incremenatally to disk when
turning on the Log ROI Voxel Time Courses (ERT) and/or Log Estimated ROI Betas (BTC) options
in the Analysis menu. With these options, however, the respective information is not saved in a
sequence of separate volume-by-volume files, but is stored in a single ".ERT" or ".BRT"file,
respectively. Data from each volume is appended incrementally to the respective file during
real-time processing.
Delayed Feedback.The Neurofeedback dialog allows to provide not only direct (ongoing)
feedback but also feedback at the end of blocks. Such "delayed feedback" of the mean level of
activity of a whole block may be helpful in the context of some clinical neurofeedback
applications. This option can be turned on by enabling the Delayed feedback option in the
Feedback type field of the Neurofeedback dialog. Click the Options button to invoke the Delayed
Feedback Settings dialog that can be used to select the protocol condition that should be used
for calculating delayed feedback values. You may also specify the data points used for
calculating the baseline value (Baseline interval) as well as the time points used to calculate the
average activation value with respect to the baseline (Modulation interval). You need also to
specify a Feedback file that will contain the stored feedback values that can be used for
providing feedback to the subject using custom software. The Update feedback file value
specifies the time point after the onset when the feedback file should be written (value must be
larger than end point of modulation interval) and the Scale beta value spin box can be used to
specify a value for scaling the estimated percent signal change beta values.
Multiple ROIs. Feedback can be based on the signal from a single open ROI or from the
combination (average) from multiple ROIs allowing to combine separately defined regions for
combined feedback. The combination of ROIs can be performed by selecting the respective
option in the Based on time course field. Options are only becoming available if multiple ROIs
are defined. In the example used for the snapshot above, two ROIs were defined and thus the
options are enabled to select ROI 1 or ROI 2 for feedback as well as the option to use the
combined signals, ROI 1 + ROI 2, as the source of neurofeedback. In the case of three ROIs, the
respective options to combine two ROIs become available as well as the option to combine all
three ROIs. While you can define more than three ROIs and observe the respective time courses
in Time Course Windows, the Neurofeedback dialog will only process the first three ROIs.
As default, the Average multiple ROIs option is enabled in the Multi-ROI integration field
allowing to combine multiple ROIs for a single neurofeedback display. When turning on the
Visualize multiple ROIs option, the data from two regions will be fed back to the subject (see
below). Note that this option only works in case that two ROIs have been defined and the
thermometer option, Activation level bar, has been selected as feedback type.
Dynamic ROIs. The option Enable best voxel selection in the Dynamic ROIs field allows to
enable the dynamic selection of voxels within a defined ROI, for details see topic dynamic ROIs.
This feature allows one to define larger ROIs and let the program automatically determine the
"best voxels" within the ROI. A disadvantage for neurofeedback is that the feedback signal might
fluctuate when the set of included voxels changes at arbitrary points in time. It is planned for a
future release to allow changes of the ROI voxels only during baseline epochs in order to avoid
this potential problem.
Bar controls. The thermometer display can be optimized for a certain purpose with the options
in the Bar controls field.
Use the Average feedback values field to specify the number of time points to calculate the
current feedback value. With the default value of "1" no averaging takes place, e.g. the
feedback value is based directly on the current ROI signal value. If this value is larger than 1,
the last N calculated feedback values are averaged to calculate the current feedback value. This
effectively implements a temporal low-pass filter. We recommend modest averaging values
between"2"and "5".
Given a baseline level bl (see below), the feedback value fb of one time point (without/prior to
averaging) is calculated for the current value val as follows:
fb = (val - bl) / bl * 100
resulting in a percent signal value. To convert this value into a thermometer display, the
resulting percent signal value is related to the maximum percent signal value as specified in the
Max PSC 1 field (the Max PSC 2 field is used for the second thermometer display in case of
multiple ROI feedback as described above). If, for example, the calculated fb value is 2,5% and
the max psc value is set to 5%, the thermometer is filled with 5 out of 10 rectangles since
fb/max_psc = 0.5. To find good values for the Max PSC entry, it might be useful to observe
achievable neurofeedback amplitudes for specific ROIs in test runs. It is also possible to enable
the Set to max measured option to automatically set the value to the maximum feedback value
calculated until the current time point.
Normally the baseline is calculated based on the "rest" or "fixation" condition prior to an active
modulation condition. Important: TBV identifies baseline condition(s) by checking the name of
each condition of the current protocol and assumes a baseline condition if the condition name
contains the string "fix", "baseline" or "rest". This check is performed case-insensitive, e.g.,
both "Fixation" and "Cond-rest" would be identified as baseline conditions. When calculating the
baseline, TBV looks in the past for a window maximally of the size specified in the Window for
baseline field. The first baseline epoch discovered will be used for baseline calculation (see
above). If the window is so large to encompass even earlier baselines, those epochs are not
included. To optimize calculation of the baseline, the values accessed actually take into account
included. To optimize calculation of the baseline, the values accessed actually take into account
the hemodynamic response delay. If, for example, the TR is 2 seconds and the last baseline
condition occurred from time points 20 - 27, the actual values used for baseline calculation will
be from 23 - 30. The used shift is calculated simply as 6 / TR (with TR in units of seconds).
As an alternative to use a baseline window, it is also possible to use the baseline value
calculated by the GLM of the ROI data (beta value of the constant predictor, also called "b0").
While this option provides a more stable baseline estimate than a sliding window, it may be
sub-optimal in case of signal drifts. To enable this feature, turn on the Use ROI-GLM baseline
(b0) option.
The Baseline display level field sets the "zero level" at a vertical position of the bar display. As
default, this value is set to "0", which means that the whole display is dedicated only for
positive feedback values. If the value is set to "1", the zero level will be between the lowest
(first) and second lowest (second) rectangle of the bar. If the baseline display level is larger
than 0, the zero level is indicated by a yellow horizontal line, which is shown in the snapshot
above for the case of a baseline display level of "2".
The Show condition name as instruction option provides a simple way to present a short
instruction to the subject to signal the begin of experimental conditions (i.e. neuromodulation
blocks vs baseline blocks). The instruction is shown below the bar display (see snapshot below,
instruction "Faces") at the beginning of a block. This provides an easy way to signal the begin
and end of blocks to the subject.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
Dynamic ROIs
Dynamic ROIs allow to automatically select a percentage of "top" voxels from a defined ROI
creating an effective sub-ROI on the fly. This feature can be turned on from the Neurofeedback
dialog (see above), which can be invoked by selecting the File > Neurofeedback menu item. To
enable dynamic ROIs, turn on the Enable best voxel selection option in the Dynamic ROIs field.
The Use top % field is set to a default value of 33%; you may change this value by using the
up/down spin buttons or by entering a value directly. A value of 33% will select a third of the
voxels of the ROI to form the optimized sub-ROI. You can observe which voxels are selected in
the Multi-Slice View, or better, in the zoomed Single-Slice View.
Benefits. Dynamic ROIs generally lead to better signal extraction from ROIs, especially in case
of coarse anatomical ROI specification. But also functional ROIs benefit from dynamic selection:
By defining rather broad initial ROIs, dynamic voxel selection ensures that the best sub-ROI will
be determined even if there are small alignment errors across successive runs or movementrelated slice shifts. It is important that functional ROIs are defined by using somewhat lowered
thresholds in localizer experiments in order to include "fringe" voxels.
How are dynamic ROIs determined? The "best" voxels are selected based on the current set
of condition beta values calculating a score based a) on the maximum condition beta value and
b) on the amount of deviation from the mean of all condition betas. The first criterion selects
those voxels, which have the largest beta value. The second criterion calculates first the mean
of all betas and then adds the absolute differences of each beta value from the mean. This
deviation index biases the selection to those voxels with a "irregular" profile, i.e. which will
show high values for contrasts between betas. The two calculated criterion values are added to
get an overall voxel score, which is finally related to the baseline signal level of a voxel, i.e.
voxel-score = (b_max + b_dev)/b_constant.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
The Stimulation Protocol Dialog
Using the Stimulation Protocol dialog, you can define the conditions for your experiment and the
intervals during which the conditions occur. A protocol file forms the basis for the statistical
analysis but is also important for visualization purposes. If you use Turbo-BrainVoyager in IFIS
mode, you do not have to create protocols because they are created automatically for you
(ultimately from the paradigms bundled with IFIS or newly created once using E-Prime).
Click the Stimulation protocol... menu item in the Analysis menu to invoke the Stimulation
Protocol dialog. You can name the paradigm in the Experiment: field as desired.
To define a new condition, click the Add button on the right side of the Condition listÂÂÂ​. You
will see "<untitled>" in the Condition listÂÂÂ​. Select the "<untitled>" entry and then click
the Edit LabelÂÂÂ​ button. The appearing text dialog allows you to change the name of the
new condition as desired. Enter a name and then press the <RETURN> button.
The most important information you have to provide next are the intervals during which the
defined condition is defined. You can enter the intervals in specific fields, which appear after
clicking the "Intervals >>" button:
In the "Intervals defining condition events / blocks" field, you can now define the intervals for
the condition currently selected in the "Condition list". There are two ways to specify a protocol:
a) Specifying the intervals numerically, i.e. for each interval of a condition, the time point when
an interval begins and the time point when the interval ends has to be entered.
b) Using a graphical procedure based on a segmented visual representation of time.
Numerical definition of condition intervals
The numerical specification of intervals is a very flexible approach, which works also in cases
when the intervals of conditions have different length (duration). To define a new interval, make
sure that the respective condition is selected in the "Condition list" (i.e. "Fixation" in the
snapshot above) and then click the "Add" button in the "Intervals defining events / blocks" field.
As a result, the NrOfIntervals field now shows that we have "1" interval defined for the currently
selected condition. If more than one intervals have been defined, the Interval field can be used
to browse them. At present, this field shows also "1" because only one interval has been
defined. As default, the begin and end point of the interval are set to "1" as shown in the From
and To fields. You may now change these values. As an example, change the To field to "8". You
can define additional intervals for this condition by pressing the Add button. Define a second
interval and set the From value to "13" and the To value to "20". Now the NrOfIntervals field
indicates that there are two defined intervals for the current condition and you can select either
one by changing the Interval field. In the snapshot below, the second interval is selected.
You can visualize the specified intervals in a graphical representation of the protocol. Click the
Plot -> Time course plot window item in the dialog's local menu to call the Time Course Plot
[Stimulation Protocol]ÂÂÂ​ dialog. As default, this dialog shows a time course with 100 data
points corresponding to the NrOfTimePoints entry in the middle of the Stimulation Protocol
dialog. You may change this value, which is, however, not necessary because it will expand
automatically if you define intervals stretching beyond 100 time points. In the Time Course Plot
dialog, you should see colored bars visualizing the conditions and intervals defined so far. Each
condition gets a default color, which is grey for the first defined condition because the first
condition defined is often a "Rest", "Baseline" or "Fixation" condition. You can change the color
used for a condition by clicking the Edit Color button next to the Condition List. If you do not see
the bars (see below), make sure that the Use Protocol option in the Time Course Plot window is
turned on.
In the same way as described for the first condition, you can add additional ones. To add a
condition, click the Add button next to the condition list in the upper half of the dialog. Change
the condtion's name using the Edit Label button. While the new condition is selected in the
Condition List, click the Add button in the Intervals defining events / blocks field to define the
first interval for that condition. Enter the value "9" in the From field and the value "12" in the To
field, which fills the period left blank by the first condition. Add another interval by clicking the
Add button and enter the value "21" in the From and "24" in the To field. The protocol defined so
far should look like in the snapshot below (the condition colors have been changed using the Edit
Color button):
In the same way, you can add further conditions and intervals for the conditions. Note that the
numerical technique allows you to define any length ("duration") for an interval and presents,
thus, a very flexible way to define protocols.
Graphical definition of condition intervals
The graphical method works well with regularly spaced conditions, i.e. if you have stimulation
periods of equal length (i.e. 8 blocks of condition 1, then 8 blocks of condition 2, then 8 blocks
of condition 1 etc.). To get a graphical representation of the protocol, click the Plot -> Time
course plot window item in the dialog's local menu to call the Time Course Plot [Stimulation
Protocol] dialog. As default, this dialog shows a time course with 100 data points corresponding
to the NrOfTimePoints entry in the middle of the "Stimulation Protocol" dialog. You may change
this value by using the spin buttons or by directly entering a new value. At the beginning, this
dialog shows a series of vertical lines located at increments of 10 time points. When the
segmentation lines are not visible, unmark the check-box Use Protocol to reveal them.
Click the spin buttons of the Size field to change the separation of the vertical segmentation
lines (here the value "8" is used). Although many protocols have a regular spacing, the
beginning and ending part of a protocol often have a different length. You do not have to care
about the ending part, but for the beginning segment, you can enter a specific length by
changing the OffsetÂÂÂ​ field. If you change the Size and Offset fields, the program
immediately updates the segmentation lines accordingly.
After setting the Size and Offset value, click with the left mouse button in all segments
belonging to the condition currently selected in the Condition List (i.e. "Fixation"). As a result,
the selected segments will be marked with horizontal yellow lines as shown below:
To convert the performed graphical specification into a numerical representation, click the Add
Set button in the Intervals defining events / blocks field of the main dialog. The started process
reads the begin and end points of the horizontal lines and stores them as a list of intervals for
the condition currently selected in the Condition List (i.e. "Fixation"). You can check the result by
looking in the respective fields in the lower part of the dialog (see yellow box in the snapshot
below). The NrOfIntervals entry now has a value of "7" corresponding exactly to the number of
horizontal line segments selected with the mouse in the Time Course Plot dialog. The Interval
field currently shows the first ("1") defined interval which is from "1", as shown in the From
field, to "4", as shown in the To field. This corresponds to the first horizontal line, which is only
"4" time points long because this value was specified in the Offset field. You can now select any
of the seven defined intervals by using the spin box of the Interval field. If you want to adjust
an interval, you can do this directly by changing the From and To fields.
The definition of the intervals is also reflected in the Time Course Plot, which now turns on the
Use Protocol option and shows seven vertical bars defining the thus far defined protocol.
The condition gets a default color (the first condition is colored grey because it is often a "Rest",
"Baseline" or "Fixation" condition), which you can change by clicking the Edit Color button next
to the Condition List.
In the described way, you can add additional conditions and define the respective intervals
graphically or numerically. You can save your completed protocol using the Save Stimulation
Protocol item in the dialog's File menu. A created protocol can then be specified in the TBV File
dialog or directly in a TBV file.
NOTE: The consistency of your protocol definitions are constantly checked in the background.
The result of this consistency check is shown in the title bar of the Stimulation Protocol dialog. If
"OK" appears, your protocol is fine. If, however, "NOT OK" is shown, your protocol contains
overlapping condition intervals and you must change the protocol.
NOTE: You can also define a protocol in "millisecond" resolution, which might be necessary for
some event-related paradigms. To define a protocol in millisecond resolution, click the
Milliseconds option in the Time units field of the Stimulation Protocol dialog. You can then define
your intervals numerically as described above. The only difference to the previous description is
that you specify the begin and end of intervals using milliseconds instead of time points
(volumes). Instead of entering absolute (large) numbers for the begin and end of an interval,
you can also use the From volume and To volume fields together with the respective Offset
[msec] fields. This allows to define the begin or end of an interval in milliseconds relative to a
time point (volume). If, for example, a condition begins 300 milliseconds after the 12th volume
(TR), you may enter "12" in the From volume field and "300" in the respective Offset [msec]
field. From these two values the program computes an absolute value in milliseconds, which is
shown in the From field. When using this approach, make sure that the the TR value has been
entered correctly since this value is used to compute the absolute value, i.e.
AbsoluteValue[msec] = Volume[number] x TR[msec] + Offset[msec].
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
The Rename DICOM Files Dialog
Turbo-BrainVoyager supports analysis of DICOM files. This allows to use the program also in
those cases for which immediate real-time processing is not possible, i.e. because a scanner
does not save processed files incrementally (volume-by-volume). Since nearly all scanners save
the data in DICOM format at the end of a functional run, it is possible to perform a "near realtime" post-run analysis. DICOM files may have very complicated file names, however, which
prevents the direct use for (near) real-time analysis because files are located by constructing
them from various parts. You may describe the file names of your DICOM files to be readable
by Turbo-BrainVoyager (see "DICOM" file format in the dialog help or the respective section of
the TBV settings file), but the names are often very complicated not matching a simple naming
scheme. This is exactly where the Rename DICOM Files tool comes in handy because it solves
this problem by converting the names of all DICOM files in a directory to fit into the following
simple naming scheme:
"<name_part>-<series_nr>-<volume_nr>-<image_nr>.dcm"
It does this by analyzing the header of each file in the specified folder. The resulting file names
can then be processed by Turbo-BrainVoyager. To rename DICOM files, click the Browse button.
In the appearing Browse For Folder dialog, select the directory containing the Dicom files to
convert. Finally click the Go button.
NOTE: The rename tool can be used for DICOM files from any scanner manufactuer. It also
supports the special Siemens mosaic dicom format, which is specified in a TBV file with the
"SIEMENS_DICOM_MOSAIC" data type.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
The Behavioral Data window
This window shows the result of behavioral responses recorded with the MRI Devices response
buttons. There are five buttons for the left hand (five upper rows) and five buttons for the right
hand (five lower rows). In addition there is a row in the middle showing omissions, i.e. no
button has been pressed in a certain trial. A small vertical bar within a row thus indicates that
the respective button has been pressed at this time point and with respect to the protocol shown
in the lower section. The color of the vertical bars indicate whether a response was correct
(green) or incorrect (red). Note that the integration of responses in the real-time processing
allows to analyze correct vs incorrect trials on the fly.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
The Plugin Interface
The plugin interface opens custom access to internal data during real-time processing including
information of ROIs, design matrix, (preprocessed) raw data and statistical information including
the content of the design matrix, beta maps and contrast t maps. This allows to perform
additional calculations within the plugin and/or to export data for external processing, e.g. in
Matlab. The plugin interface also allows to visualize calculated maps on slices, volumes and
surfaces in the same way as the standard GLM contrast maps.
Note that for maximum efficiency the API provides direct pointers to internal data structures
without any "buffering" in between. The source code for the two plugins is included with this
release allowing to quickly learn about the provided API functions. The "TBVPluginInterface.h"
file lists all available commands for which a detailed description will be available soon.
A plugin needs to be coded in C++. Available templates and examples allows for simple
creation of own plugins requiring only to fill-in one (or more) "execute" functions and to
customize a few C functions used to interrogate plugin information such as its display name. The
main task of the plugin coder consists in adding code to the "executePostStep()" function that is
called at each time point during real-time processing.
The next topic describes how to use implemented plugins from TBV; then it is described when
and how TBV calls a selected plugin before, during and after real-time processing; this
information is helpful to learn how to write the called plugin functions.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
Using Plugins
When one clicks the Plugins menu, a list of all available plugins will be shown. To fill the Plugins
menu, the program looks into the "Plugins_32" (32-bit TBV on 32 or 64-bit operating system) or
"Plugins_64" (64-bit TBV on 64-bit operating system) subfolder within the "TBVExtensions"
folder. If one wants to install new compiled plugins, simply copy the respective library file
(extension ".dll" on Windows, ".so" on Linux, ".dylib" on Mac) in that folder.
The "TBVExtensions" folder is located itself within the Documents folder. On Windows XP, the
Documents folder is typically accessible via the "My Documents" directory in Explorer or through
the full path "C:\Documents and Settings\<USER>\My Documents" (these names may vary
depending on the used language and the version of the Windows operating system). On Windows
Vista and Windows 7, the "Documents" folder is located in "C:\Users\<USER>\Documents". On
Mac OS X and Linux, the "Documents" folder is located within your "Home" folder, i.e.
"/Users/<USER>/Documents" on Mac OS X and "/home/<USER>/Documents" on Linux. If the
Documents folder is not already existing on your Linux system, it is created during installation
of BrainVoyager QX. Note that the directory structure in newer Windows operating systems
(Vista/7) is similar to the Linux and Mac OS X folder layout. The snapshot below shows the
"Plugins" folder on a 64-bit Mac OS X system.
To start a plugin, simply click its name in the Plugins menu. Note that one needs to start a
plugin prior to real-time processing since the Plugins menu will not be accessible during
incremental processing. TBV then opens and shows the Plugin window containing a Log text field
that is used by the plugin to inform the user about ongoing processing. The messages appearing
in the Log fully depend on the plugin code, i.e. they are unique to the executed plugin. The
plugin may print some information about its operation to the Log and it can also ask for
information such as choices for subsequent real-time processing and it will then waiting until it
is called repeatedly during real-time processing. The snapshot below shows the Plugin window
after selecting the "Example Plugin - Export Volume Data" plugin. Note that the title bar of the
dialog shows the name of the plugin. The message printed to the Log is the result of a choice
made when the plugin asked to export various kinds of information including preprocessed raw
data, beta maps (chosen) and t maps.
When starting real-time processing, the plguin is called during processing of each incremental
time step and it can access all relevant internal data of TBV. The snapshot below shows a
snapshot during real-time processing; the plugin has just been called at time point "74" and
informs the user that it saves 4 beta maps to disk. The plugin also presents extracted
information about the content of the used design matrix at each step.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
TBV - Plugin Interactions
When the Plugins menu is opened, TBV is interrogating all plugin files (shared libraries with the
extension ".dll" on Windows, ".so" on Linux and ".dylib" on Mac OS X) located in the
"Plugins_32/64" folder. In each detected plugin library file, TBV calls a few simple C functions
that must be defined in the plugin in order to get basic information about the plugin such as its
name, a short description of its function, the plugin author and (optionally) a help file. The
returned plugin name is used to fill the Plugins menu.
When a specific plugin is selected in the Plugins menu, TBV will create a plugin object by
instantiating the defined plugin class; more specifically, the "createPlugin()" C function is called
that serves as a factory to create the plugin object; a pointer to that object is returned to TBV
and stored so that it can be used subsequently to call predefined methods that must be
implemented by the plugin class. In order to enforce a set of known class methods, a plugin
class must be derived from the generic "TBVPluginInterface" class defining the interface using
virtual functions.
The plugin object is normally destroyed by TBV when the user closes the Plugin dialog typically
after real-time processing. The plugin object is also destroyed when the initialization function
"initPlugin()" returns "false", e.g. in case that some prerequisites are not met. If "initPlugin()"
returns "true", the Plugin dialog is launched which is used to send information from the plugin to
the user. ThenTBV calls the "executePreRun()" function that can be used for setting up the plugin
or to interrogate information from the user. After that function has returned, the plugin "sleeps"
until it is called later. After real-time processing has been started, the "executePreStep()" and
"executePostStep()" functions will be called once at each time point allowing execution of code
for custom data processing/export. Note that the plugin programmer is responsible for keeping
processing time within these functions short since TBV will wait until the plugin returns, i.e. until
these functions have finished its computations at a given step. After incremental processing is
finished, TBV calls the "executePostRun()" function of the active plugin that can be used to do
final processing. When the Plugin dialog is closed, the destructor of the plugin object is called
that can be used for final clean-up such as releasing any allocated memory. In summary, the
following functions are called in a typical real-time session:
When selecting a plugin in the Plugins menu:
1. TBV calls C-function createPlugin() of the plugin that calls itself "new
<PluginClass>" to create plugin object, executes constructor, and returns object
pointer (called "pluginObject" below).
2. TBV calls member function "pluginObject->initPlugin()" allowing plugin to check
prerequisites, including successful access of TBV plugin API functions and to check
whether the TBV version is appropriate.
3. TBV calls member function "pluginObject->executePreRun()" allowing plugin to
perform setup operations (e.g. allocating memory for later use) and to present
dialogs to the user to make specific choices or to enter relevant information (e.g.
where to store data).
At each time step after starting real-time processing:
4. TBV calls member function "pluginObject->executePreStep()". This function allows
to access the raw data of a functional volume after all slices have been read into
working memory. This allows, for example, to add additional preprocessing
operations such as custom spatial smoothing.
5. TBV calls member function "pluginObject->executePostStep()". This function is
called after preprocessing (e.g. motion correction, spatial smoothing) as well as
statistical GLM processing has been performed. This implies that beta and contrast
maps have been updated for the new functional volume only at this point. Since
data has been preprocessed and updated, it is recommended to mainly use this
function for custom processing and data export (see example "export" plugin).
After the last volume has been processed:
6. TBV calls member function "pluginObject->executePostRun()" allowing to do some
post-run processing and to inform user about completion of the plugin.
When user closes the Plugin dialog:
7. TBV deletes the plugin object executiong the "delete pluginObject" statement. This
results in a call of the plugin destructor that can be used to clean-up any allocated
memory.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
Writing Plugins
Essential Plugin Files
A plugin needs to derive its plugin definition from the "TBVPluginInterface" class. The
"TBVPluginInterface.h" file must, thus, be added to any TBV plugin project containing your
custom .cpp file(s). Since it is intended to not change the currently provided access functions
but only to add new functions, updating the "TBVPluginInterface.h" include files does not require
changing any of the files containing your own code, i.e. it will be possible to overwrite the file
with a new version and to recompile the plugin code. Updating the "TBVPluginInterface.h" file
will only be necessary if you want to use additional functionality of Turbo-BrainVoyager made
eventually available with new releases. The latest "TBVPluginInterface.h" include file is provided
with the source code of the example plugins (and eventually via download from our web site).
The snapshot below shows part of the "TBVPluginInterface.h" file defining the abstract plugin
class with essential virtual methods that need to be implemented in the derived plugin class.
Following the class definition, the "TBVPluginInterface.h" file contains definition of access
functions with parameter types that can be used in the plugin class. The snapshot below shows
the beginning of the TBV API. The "tLogText" command, for example is defined with a "void"
return type and one input parameter that is a pointer to a c string. In the plugin code it will be
possible to write commands like "tLogText("Hellow from Plugin")" and the provided text will be
visible to the user in the Log text field of the Plugin dialog. The available commands will be
described in more detail in subsequent topics.Following the definition of the signature of the TBV
API functions, a "InitTBVAccess()" function (not shown) is defined that retrieves the
corresponding function pointers from TBV at run time.
Besides the "TBVPluginInterface.h" file, a new plugin needs as a minimum only one C++ and
one header file defining the custom plugin class, e.g. a "MyPlugin.cpp" file and a "MyPlugin.h"
file. The provided plugin examples contain an additional "global.h" header file that is only used
to determine the platform on which the plugin is compiled in order to include platform-specific
standard C/C++ header files. Depending on the needs of your plugin, you may, of course,
additional C/C++ files that support your programming goals, e.g. files from "Boost" or
"Numerical Recipes". The snapshot below shows the complete "SaveVolumeDataPlugin.h" header
file from the "Export Volume Data" example plugin.
As described, the custom class includes the "TBVPluginInterface.h" header file allowing to derive
the custom class "SaveVolumeDataPlugin" from the abstract "TBVPluginInterface" class. Within
the class declaration, all methods that were defined "virtual" in the abstract class are now nonvirtual and need to be defined in the implementation file "SaveVolumeData.cpp". Note that for a
new plugin, one only needs to change the class name. The only special part in this example are
the definitions of two protected variables "stepCounter" and "ExportChoice" that are used in the
plugin to store information across different calls from TBV. You would remove these variables
for your own plugin and add other variables as needed. The second part of the plugin header file
contains declarations of the described C functions that need to be defined in the implementation
plugin file; these functions will be called from TBV to retrieve basic information about the
plugin. Note that this part needs not to be changed. The snapshot below shows part of the
"SaveVolumeData.cpp" plugin class implementation file.
The constructor and destructor are empty in this example plugin. In case you allocate data on
the heap in the constructor (or "initPlugin()" function), you should release that memory in the
destructor. The "initPlugin()" function is used to establish access to the TBV API calling the
"InitTBVAccess()" function that is defined in the "TBVPluginInterface.h" header file. It is
important to check that this function succeeds; if it does not succeed calling any TBV API
command will result in a crash since the function pointers could not be retrieved; as can be
seen above, the "initPlugin()" function returns in that case with a value "false" indicating to TBV
that the plugin can not be used. If successful, the "initPlugin()" function finally checks whether
the version of the running TBV program is sufficiently high to support the subsequently used API
functions. Since at this point the access to the TBV API was successful, this part can use the TBV
API functions "tGetVeersionOfTBV()" and "tMessageBox()". The
"checkVersionGreaterEqualVersion()" function is always available since it is defined in the
"TBVPluginInterface.h" file. While you can put any code you want in the "initPlugin()" definition,
it is recommended to simply use the function as described for your own code (eventually
modifying the required TBV version). Note that the class name needs to be changed for all class
methods, e.g. instead of "bool SaveVolumeDataPlugin::initPlugin()" you would use something
like "MyPlugin::initPlugin()". The snapshot below shows the next section of the
"SaveVolumeData.cpp" file.
The "executePreRun()" function can be used to prepare real-time processing or to ask the user
to provide relevant information. This function is called once from TBV after the call to the
"initPlugin()" function. In the example plugin, the user is asked to make a choice about the type
of data to export to disk at each step during subsequent real-time processing. The choice is
presented using a dialog that is invoked using the "tGetIntegerInput()" API function. Note that it
is not allowed to use such blocking GUI API functions during real-time processing, i.e. in the
code of the "executePreStep()" and "executePostStep()" functions since this would interfere with
real-time processing. The "executePreStep()" function is not used in the example plugin simply
returning "true" to TBV; since the data of a new volume is not preprocessed at this stage, this
function can be used to perform custom preprocessing replacing TBV's standard preprocessing,
e.g. by implementing an own motion correction routine after turning off motion correction in the
TBV Settings dialog. The most important function of a plugin is the "executePostStep()" function
that is called at each step during real-time processing just after all TBV analysis steps have
been performed. In the example, the function begins with increasing the instance variable
"stepCounter" that was declared in the header file (see above). Then some relevant information
is retrieved such as the name of the project (used to name exported files) and the target folder
specified in the TBV settings file; the user is informed that the exported data from this plugin is
stored in that folder using the "tLogText()" API function. The value of the currently analyzed
time step is retrieved by the "tGetCurrentTimePoint()" API function. Inspect the full definition of
the "executePostStep()" function in the provided example plugins to learn about the offered
possibilities. The snapshot below shows the final part of the "Export Volume Data" example
plugin code defining the C functions declared in the header file.
As can be seen, the "createPlugin()" function creates a plugin object by instantiating the plugin
class using the "new" operator. The obtained pointer to the plugin object is returned and used by
TBV to call the class functions that have been described above. The "getPluginName()" C
function returns a string containing the name of the plugin; TBV uses that string to represent the
plugin in the Plugins menu. The "getPluginDescription()" C function provides a descriptive string
summarizing the purpose of the plugin. The "getAuthor()" function returns information about the
author of the plugin. The "getHelpFile()" function may return a link to a HTML file containing
additional help information about using the plugin; here an empty C string is returned, i.e. no
help file is provided; since TBV plugins are usually used internally (as opposed to BVQX
plugins), a help file targeted to other users is probably not necessary in most cases. The final C
function returns a version string (currently not used, but it might be helpful for the plugin
developer to identify major revisions of a plugin).
Compiling Plugins
It should be possible to write a plugin with your favorite compiler and Integrated Development
Environment (IDE). On Windows, the Microsoft Visual C++ compilers in Visual Studio 2005/2008
compilers have been tested and can be used to create plugins. On Mac OS X, you can uxe XCode
or QtCreator and on Linux you can use QtCreator or KDevelop. On Mac and Linux, the provided
Brain Innovation plugins have been compiled directly from the console using the GNU gcc
compiler or with Qt Creator. While Qt Creator is a cross-platform IDE from Nokia (which
acquired Trolltech, the original creator of the Qt library) to develop C++ software using the Qt
library, it can be used also to develop any (non-GUI) C/C++ program/library. Project files
(Visual Studio project ".vcproj" file for Windows, Makefiles for Mac and Linux) are provided that
can be adapted for use with own plugins.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
General Access Functions
void tGetVersionOfTBV(int *major, int *minor, int *subminor)
The "tGetVersionOfTBV" function returns the version of the running Turbo-BrainVoyager in the
variables "Major", "Minor" and "SubMinor". Usually used in the "initPlugin()" function. The
returned version values can be used to check whether the used version of TBV is recent enough
to ensure that all TBV API functions used in the plugin are available. For this test, you can use
the "checkVersionGreaterEqualVersion()" function, for details check the source code of the
provided example plugins.
void tGetTBVPath(char *cTBVPath)
Use this function to retrieve the path to the folder containing the Turbo-BrainVoyager
executable. On Windows, for example, this will typically result in a C string like "C:/Program
Files/TurboBrainVoyager". Note that slashes are returned on all platforms in Unix convention
(right slashes) and that the path does not end with a slash (except when a root directory is
returned).
void tGetPluginsPath(char *cPluginsPath)
This function retrieves the path to the folder containing BrainVoyagerQX plugins. Use this
function to find the location of your plugin and any subfolders (i.e. directories containing help
files or resource files). On Windows, for example, this function will typically result in a C string
like "C:/Documents and Settings/<User>/My Documents/BVQXExtensions/Plugins". Note that
slashes are returned on all platforms in Unix convention (right slashes) and that the path does
not end with a slash (except when a root directory is returned).
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
GUI Functions
void tLogText(const char *text)
This function sends a line of text to the Log text field in the Plugin window of TurboBrainVoyager. The text is provided as a C string. This function is the only GUI function during
real-time processing and should be used to provide information about (successful) processing in
the plugin; it is also useful to help debugging plugin code.
void tMessageBox(const char *message)
This function displays a message box with text provided in the "message" C string. This function
can not be used during real-time processing; the appropriate place to use it is the
"executePreRun()" function.
int tGetIntegerInput(const char *instruction, int default_value, int min_val, int max_val)
Presents a dialog with the provided "instruction" text and an edit field in which the user can
enter an integer value in the range "min_val" to "max_val". The edit field shows the provided
"default_value" initially. When the user clicks the "Ok" button of the dialog, the entered value is
returned. If the special value "min_val - 1" is returned, the user has clicked the "Cancel" button
or pressed the "Escape" key. This function can not be used during real-time processing.
float tGetFloatInput(const char *instruction, float default_value, float min_val, float max_val)
Presents a dialog with the provided "instruction" text and an edit field in which the user can
enter a float (real) value in the range "min_val" to "max_val". The edit field shows the provided
"default_value" initially. When the user clicks the "Ok" button of the dialog, the entered value is
returned. If the special value "min_val - 1" is returned, the user has clicked the "Cancel" button
or pressed the "Escape" key. This function can not be used during real-time processing.
int tGetTextInput(const char *instruction, const char *default_text, char *return_text)
Presents a dialog with the provided "instruction" text and an edit field in which the user can
enter a string, i.e. a file name. The edit field shows the provided "default_text" text initially.
When the user clicks the "OK" buttton of the dialog, the entered text is returned in the
"return_text" parameter. Note that you must provide enough space for the C string "return_text"
(see example code for more information). The return value signals success (value "1") or failure
("0"). This function can not be used during real-time processing.
int tYesNoMessageBox(const char *cquestion)
Presents a dialog with the provided text "question" and with a "Yes" and a "No" button. The
function returns value "1" if the user clicks "Yes" and value "0" otherwise. This function can not
be used during real-time processing.
int tGetOpenFileName(const char *instruction, const char *default_folder_file, const char *type_of_files, char *return_filename)
Presents a standard "File Open" dialog with the provided "instruction" text. The contents of the
folder provided in the "default_folder" parameter will be shown in the dialogs file browser
initially. The "type_of_files" parameter can be used to filter the files in a folder with respect to a
provided file type. You must use the syntax "<File Type> (*.<Extension>)" to specify a filter,
i.e. "Protocol Files (*.prt)". When the user clicks the "Open" buttton of the dialog, the selected
file name is returned in the "return_filename" parameter. Note that you must provide enough
space for the C string "return_filename" (see example code for more information). The return
value signals success (value "1") or failure ("0"), the latter indicating that the user has clicked
the "Cancel" button. This function can not be used during real-time processing.
int tGetSaveFileName(const char *instruction, const char *default_folder_file, const char *type_of_files, char *return_filename)
Presents a standard "File Save" dialog with the provided "instruction" text. The contents of the
folder provided in the "default_folder_file" parameter will be shown in the dialogs file browser
initially. If not only a path but also a filename is provided, the filename will be used as the
default name for the to-be-saved file. The "type_of_files" parameter can be used to filter the
files in a folder with respect to a provided file type. You must use the syntax "<File Type>
(*.<Extension>)" to specify a filter, i.e. "Protocol Files (*.prt)". When the user clicks the "Save"
buttton of the dialog, the selected file name is returned in the "return_filename" parameter.
Note that you must provide enough space for the C string "return_filename" (see example code
for more information). The return value signals success (value "1") or failure ("0"), the latter
indicating that the user has clicked the "Cancel" button. This function can not be used during
real-time processing.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
Basic Project Functions
int tGetCurrentTimePoint()
Provides the number of the currently processed step during real-time processing as an integer.
Note that this function is 1-based, i.e. when the first step is processed the function returns "1"
not "0"; this is important when the return value is used to access time-related information; in
this case subtract "1" from the returned value.
int tGetExpectedNrOfTimePoints()
Provides the number of time points as an integer. The name contains the term "expected" since
a real-time run might be interrrupted by the user, i.e. this is the intended number of volumes as
specified in the TBV settings file.
void tGetDimsOfFunctionalData(int &dim_x, int &dim_y, int &dim_z)
Provides the dimensions of the functional volumes; "dim_x" and "dim_y" are the dimensions of
the slices constituting the volume and "dim_z" corresponds to the number of slices.
void tGetProjectName(char *cProjectName)
Provides the name of the project as specified in the TBV file as a C string; note that the
provided pointer must point to a pre-allocated array that is large enough (a buffer of 100 bytes
should be sufficient). The returned name can, for example, be used as part of names identifying
exported data (see example "Export Volume Data" plugin).
void tGetWatchFolder(char *cWatchFolder)
Provides the path of the "watch folder" as specified in the TBV file as a C string;note that the
provided pointer must point to a pre-allocated array that is large enough for the returned path
(a buffer of 513 bytes is recommended).
void tGetTargetFolder(char *cTargetFolder)
Provides the path of the "target folder" as specified in the TBV file as a C string; note that the
provided pointer must point to a pre-allocated array that is large enough for the returned path
(a buffer of 513 bytes is recommended). The target folder can be used to export data for
custom processing (see example "Export Volume Data" plugin).
void tGetFeedbackFolder(char *cFeedbackFolder)
Provides the path of the "feedback folder" as specified in the TBV file as a C string; note that
the provided pointer must point to a pre-allocated array that is large enough for the returned
path (a buffer of 513 bytes is recommended). The feedback folder can be used to store the
result of custom calculations, e.g. providing custom input for the "Presenter" software tool.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
Protocol, DM, GLM Functions
int tGetCurrentProtocolCondition()
Provides the index of the currently "active" condition of the protocol (0-based), i.e. the conditon
that has a defined interval enclosing the current time point.
int tGetFullNrOfPredictors()
Provides the number of predictors of the design matrix. Note that this function returns the "full"
number of intended predictors while the "tGetCurrentNrOfPredictors()" returns the number of
predictors currently in use.
int tGetCurrentNrOfPredictors()
Provides the currently effective number of predictors. Note that this function may return a
smaller number than the "tGetFullNrOfPredictors()" function since the internal GLM calculations
use a restricted set of predictors in case that for one or more predictors not enough non-zero
data points are available. Roughly speaking, the number of current predictors increases each
time when a new condition is encountered during real-time processing.
int tGetNrOfConfoundPredictors()
Provides the full number of confound predictors. To get the full/effective numer of predictors-ofinterest, subtract the returned value from the "tGetFullNrOfPredictors()" or
"tGetCurrentNrOfPredictors()" function, respectively.
float tGetValueOfDesignMatrix(int pred, int timepoint)
Provides the value of a predictor at a given time point of the current design matrix. Note that
the design matrix always contains the "full" set of predictors, a reduced set of predictors is only
used internally (predictors that are not used internally are those containing only "0.0" entries up
to the current time point). Note that the "timepoint" parameter must be smaller than the value
returned by the "tGetCurrentTimePoint()" function. For details, see the provided example
plugins.
int tGetNrOfContrasts()
Provides the number of (automatically or manually) specified contrasts in the TBV settings file.
This value is important for accessing t maps, see the "tGetMapValueOfVoxel()" and
"tGetContrastMaps()" functions.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
ROI Functions
int tGetNrOfROIs()
Provides the number of currently available ROIs. Note that the number of ROIs may change
during real-time processing since the user may open additional ROI windows or close ROI
windows at any time. It is thus important to use this function prior to other functions accessing
ROI information.
float tGetMeanOfROI(int roi)
Returns the mean signal value of the ROI referenced with the "roi" parameter (0-based index).
A valid number must be smaller than the value returned by the "tGetNrOfROIs()" function. Note
that the voxels defining a ROI might change in case that the user selects another region for the
same ROI index (replaces the content of the same plot in the GUI). The function should be used
in situations when ROIs are not changed, i.e. when a set of ROIs is pre-loaded for a
neurofeedback study. For details, see the "ROI Processing" example plugin.
int tGetNrOfVoxelsOfROI(int roi)
Provides the number of voxels of the specified ROI. Note that the returned number might
change during real-time processing in case that the user replaces a ROI with another set of
voxels. The value of this function is important for accessing information of individual ROI voxels
(see below).
float tGetBetaOfROI(int roi, int beta)
Retrieves the value of a specified beta (0-based index) of the specified ROI (0-based index). For
each ROI a GLM is calculated incrementally using the mean signal time course; the betas of the
calculated GLM are accessible with this function; note that the beta indices range from 0 to the
full number of predictors; to retrieve only the betas of the predictors of interes, the beta index
must be smaller than "tGetFullNrOfPredictors()" minus "tGetNrOfConfoundPredictors()". For
details, see the "ROI Processing" example plugin.
bool tGetCoordsOfVoxelOfROI(int roi, int voxel, int &x, int &y, int &z)
Provides the coordinates of a voxel (0-based enumeration index) of the ROI specified with the
"roi" parameter (0-based index); the value for the "voxel" index ranges from "0" to one less
than the value returned by the "tGetNrOfVoxelsOfROI()" function; since ROIs content may
change, use the latter function for a specific ROI index always before using the current function.
For details, see the "ROI Processing" example plugin.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
Volume Data Access Functions
float tGetValueOfVoxelAtTime(int x, int y, int z, int timepoint)
Provides the signal value as a 4-byte float value of the voxel specified by the coordinate
parameters "x", "y" and "z" for the given time point (0-based indices). The given "timepoint"
parameter must be smaller than the value obtained by the "tGetCurrentTimePoint()" function.
This function should be used in the "executePostStep()" function since at this call all specified
TBV preprocessing steps have been already performed such as 3D motion correction or 3D
spatial smoothing. For details, see the "Export Volume Data" example plugin. To get raw signal
data, use this function in the "executePreStep()" function. Note, however, that the data is only
un- preprocessed for the actual time point ("tGetCurrentTimePoint() - 1") since past values will
have been preprocessed; this conceptual point needs not be considered in case that nol
preprocessing options are enabled in the TBV settings file.
short int **tGetTimeCourseData()
Provides a direct pointer to the full time course data that is also used internally in TBV.
Individual values are 2-byte short integers. The data is organized in a [time][voxel] manner,
i.e. the first index addresses a volume at a specific time point while the second index addresses
a voxel index; if a voxel with specific coordinates needs to be accessed, use the term
"z_coord*dim_x*dim_y + y_coord*dim_x + x_coord". For details, see the provided example
plugins.
double tGetBetaOfVoxel(int beta, int x, int y, int z)
Provides the value of a beta indexed by the "beta" parameter as a 8-byte double value for the
voxel specified by the coordinate parameters "x", "y" and "z" (0-based indices). This function
allows to access estimated beta values resulting from the incremental GLM performed by TBV.
Note that the beta index ranges from 0 to the current number of predictors; to retrieve only the
betas of the predictors of interest, the beta index must be smaller than
"tGetCurrentNrOfPredictors()" minus "tGetNrOfConfoundPredictors()". For details, see the
"Export Volume Data" example plugin.
double *tGetBetaMaps()
Provides a direct pointer to the full stack of beta maps that is also used internally in TBV.
Individual entries are high-precision 8-byte double values. The data is organized as a flat array;
in order to obtain the beta value of a specific predictor index for a voxel with specific
coordinates, use the term "beta_i*dim_xyz + z_coord*dim_xy + y_coord*dim_x + x_coord".
Note that the beta_i index must be in the ranges from 0 to the current number of predictors; to
retrieve only the betas of the predictors of interest, the beta index must be smaller than
"tGetCurrentNrOfPredictors()" minus "tGetNrOfConfoundPredictors()". For details, see the
provided "Export Volume Data" plugin.
float tGetMapValueOfVoxel(int map, int x, int y, int z)
Provides the value of a t map indexed by the "map" parameter as a 4-byte float value for the
voxel specified by the coordinate parameters "x", "y" and "z" (0-based indices). This function
allows to access calculated contrast values that are calculated based on the beta values from
the incremental GLM performed by TBV. The "map" index ranges from 0 to one less than the
number of contrasts specified in the TBV settings file (implicitly or via a specified contrast ".ctr"
file); the number of contrasts can be retrieved using the "tGetNrOfContrasts()" function. For
details, see the "Export Volume Data" example plugin.
float *tGetContrastMaps()
Provides a direct pointer to the full stack of contrast maps that is also used internally in TBV.
Individual entries are 4-byte float values. The data is organized as a flat array; in order to
obtain the t value of a specific contrast map index for a voxel with specific coordinates, use the
term "map_i*dim_xyz + z_coord*dim_xy + y_coord*dim_x + x_coord". The "map_i" index
ranges from 0 to one less than the number of contrasts specified in the TBV settings file
(implicitly or via a specified contrast ".ctr" file); the number of contrasts can be retrieved using
the "tGetNrOfContrasts()" function. For details, see the provided "Export Volume Data" plugin.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
Map Visualization Functions
In case that a plugin calculates its own maps in real-time, the following functions allow to
visualize them in all brain views including slices, volumes and surfaces. A plugin needs to
register the intention to visualize maps which will add in the user interface the Show plugin maps
option that allow the user to switch between visualization of the standard GLM contrast maps and
the calculated plugin maps. To see how the map visualization functionality works from a user
perspective, run the included real-time ICA plugin.
bool tRegisterMaps(int n_maps)
Registers a stack of maps for each slice of the data, i.e. if you calculate one overlay map, the
value should be "1". If you register more than one map, you can visualize several maps
simultaneously up to a maximum of 4 maps. The return value indicates whether the function was
successful. Note that this function must be called in the "executePreRun()" function. In order to
properly access the allocated data during real-time processing, use the
"tGetDimsOfFunctionalData()" function and the "tGetPluginMaps()" function (see below) when
your "executePostStep()" function is called.
void tSetPluginMapName(int map_i, char *cName)
Sets the name for the specified map "map_i" to "cName". This function can be used in the prerun step as well as during real-time processing. The specified name is shown in the map list on
the right upper part of the main program window replacing the standard list of contrasts in case
that the Show plugin maps option is turned on.
void tSetDisplayStatusOfMap(int map_i, int display_status)
Sets the "display_status" for the specified map "map_i". This function can be used in the pre-run
step as well as during real-time processing. The specified value can be "0" (do not show this
map), "1" (show positive values of map), "2" (show negative values of map) and "3" (show
positive and negative values of map). Only those map entries are shown that pass the current
threshold. The first map is turned on by TBV as default, i.e. if you calculate one map, you may not
need to use this function.
void tUpdateMapList()
This function updates the list displaying the calculated maps in the list box in the right upper
corner of the program window. It should be called after calls to the "tSetPluginMapName()" and
"tSetDisplayStatusOfMap()" have been made in order to reflect the changes in the GUI.
void tSetPluginMapsThreshold(float threshold)
Sets the "threshold" value used for the calculated and displayed maps. This function can be used
in the pre-run step as well as during real-time processing. Only those voxels in the displayed
map(s) are shown that pass the specified threshold. Note that at present no cluster threshold is
used.
void tShowPluginMaps(bool show_status)
Toggles programmatically between display of custom maps ("show_status" set to "true") and
standard GLM contrast maps ("show_status" set to "false"). You should use this function only in
the "executePreRun()" stage to turn display of plugin maps on since during real-time processing
the user can use the Show plugin maps option to control the display mode.
float *tGetPluginMaps()
Returns the pointer to the memory space reserved for the custom plugin maps or "NULL" in case
of failure. In order to properly access the allocated data during real-time processing, use the
"tGetDimsOfFunctionalData()" function and the number of maps provided to the
"tRegisterMaps()" function. Fill the reserved memory with the results of your custom map
calculation routine. Note that this function can be only called during real-time processing since
the data is not reserved directly when registering the maps but only at the moment when the realtime processing starts.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
Multi-Voxel Pattern Classification
Multi-voxel pattern classification (MVPC) is gaining increasing interest in real-time fMRI data
analysis (e.g. LaConte et al., 2007; Sorger et al., 2010) and in the neuroimaging community in
general because it allows to detect differences between conditions with higher sensitivity than
conventional univariate analysis by focusing on the analysis and comparison of distributed
patterns of activity. In such a multivariate approach, data from many voxels are jointly
analyzed. The high sensitivity of MVPC allows "brain reading" applications that aim to decode
("predict") specific mental states or representational content from fMRI activity patterns. After
performing a "training" or "learning" phase, this prediction requires little computational load and
it is, thus, suitable for real-time fMRI including brain-computer interface (BCI) applications.
Version 3.0 of Turbo-BrainVoyager introduced multi-voxel pattern classification based on the
widely used support vector machine (SVM) learning algorithm. Training and testing (prediction)
is controlled in two separate steps. In the Analysis menu, the SVM Training item can be used to
open the Multi-Voxel Pattern Classification dialog allowing to train a SVM on the data from one
or more completed runs of a real-time session; the dialog can also be used to perform offline
testing, e.g. on the data of a completed run. For trial-by-trial real-time classification, the RealTime SVM Classification dialog can be used that can be invoked by clicking the Real-Time SVM
Classification item in the Analysis menu. After training, this dialog allows to analyze trials of a
new run incrementally producing prediction values that indicate to which class a distributed
activity pattern belongs (if successful).
References
LaConte, S. M., Peltier, S. J., & Hu, X. P. (2007). Real-time fMRI using brain-state classification.
Human Brain Mapping, 28, 1033-1044.
Sorger, B., Peters, J., van den Boomen, C., Zilverstand, A., Reithler, J. & Goebel, R. (2010).
Real-time decoding of the locus of visuospatial attention using multi-voxel pattern classification.
Proceedings of the Human Brain Mapping Conference.
Turbo-BrainVoyager uses LIBSVM for training SVM classifiers:
Chih-Chung Chang and Chih-Jen Lin, LIBSVM: a library for support vector machines, 2001.
Software available at http://www.csie.ntu.edu.tw/~cjlin/libsvm
COPYRIGHT
Copyright (c) 2000-2009 Chih-Chung Chang and Chih-Jen Lin
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
3. Neither name of copyright holders nor the names of its contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
SVM Training
The Multi-Voxel Pattern Classification dialog can be used to train support vector machines
(SVMs) to associate distributed activity patterns with class labels that correspond to two or
more conditions ("classes") of a paradigm. The Trial Estimation tab is used to specify how
responses should be estimated for individual trials at each voxel. The Train SVM Classifier tab is
used to create training data for a specified region-of-interest (ROI) from the whole-brain trial
response data and to perform the actual training process. The classifier supports multi-class
problems, i.e. distributed patterns can be assigned to two or more different conditions. The
trained classifier can then be tested on completed run data using the Test Classifier tab. For
real-time classification, use the Real-Time SVM Classification dialog.
Trial Estimation
In order to obtain training exemplars for different classes, response values are extracted or
estimated for each individual trial as opposed to estimating a voxels mean response of a
condition in a standard GLM. Estimated single-trial responses across relevant voxels (e.g. from
a region-of-interest) then form the feature vectors used to train the classifier. The estimated
trial response might be as simple as the activity level at a certain time point (e.g. at the time of
the expected hemodynamic peak response) or the mean response of a few measurement points
around the peak response relative to a pre-stimulus baseline. In TBV, however, a GLM is used to
fit an expected hemodynamic response to measured single trial data. The beta value or t value
(default) estimating the amplitude of the hemodynamic response is then used as the trial
response value.
To add time course data for training trials from one or more completed runs, the "+" button in
the Input data field can be used. The selected FMR run data will be listed in the Time course
data box in the Input data field (see snapshot above). From a selected functional data file, the
referenced protocol is shown in the Protocol text field and the associated experimental
conditions are extracted and displayed in the Protocol condition selection box for the currently
selected file. Note that Turbo-BrainVoyager at present only supports protocols in "Volumes"
resolution for pattern classification. For the displayed example data, the conditions displayed
are "resting", "motor imagery", "mental calculation" and "inner speach". The first two main
conditions are selected automatically as targets for single-trial estimation. The first condition is
skipped under the assumption that it corresponds to a "baseline" or "rest" condition. It may be
useful to select additional conditions (e.g. "inner speach" in this example) in case that multiple
pair-wise classifications or multi-class classifications are planned. If more than two conditions
are included and the pairwise training option will be used in the Train SVM Classifier tab, any
two pairs can be selected for training. If the multi-class option will be chosen later, all
conditions included at this stage in the Protocol condition selection box will be used as class
labels to train the classifier.
The trial estimation step calculates a GLM for each trial per voxel by creating a data window
around trial onset. For estimating beta or t values (see below) with single-trial GLMs, a twogamma hemodynamic response function (HRF) is used. The data window for a trial is specified
with respect to the onset of a trial as specified in the protocol(s) of the included FMR data
set(s). The Pre-onset spin box can be used to specify how many data points should be included
before the trial onset data point. The offset of the trial data window can be either specified
absolutely or with respect to the duration of the trial as specified in the protocol. If the Use trial
duration option is turned off, the end of the trial window is specified with the Post-onset spin
box specifying the number of time points included after the stimulus onset point. If, for
example, the pre-onset value is 2 and the post-onset value is 8, the data window used for
estimating the trial response would be w = pre-onset + 1 + post-onset = 11 data points.
Clicking the Auto button after setting the pre-onset interval will provide a value for the postonset interval, ensuring that the interval is just long enough to let the expected BOLD response
turn back (largely) to baseline. The described way to specify the trial data window is well-suited
in case that all trials have the same duration. In case that trials of a condition may have
different durations, the trial duration option should be used to specify the data window. If the
Use trial duration option is turned on, the offset is determined by the trial duration plus the
value specified in the Post-trial spin box as w = pre-onset + trial-duration + post-trial; in case
of a pre onset value of 2, a post-trial value of 4 and a trial duration of 5 this would, for
example, result in a data window of w = 2 + 5 + 4 = 11 data points. Note that for both versions
available to specify the trial data window, the duration of a trial as specified in the protocol will
be used to determine a box-car reference function that is set to 1 at the trial onset data point
and subsequent points reflecting the trial duration, e.g. 0 0 1 1 1 1 1 0 0 0 0 in the described
example case. The constructed box-car reference is finally submitted to the two-gamma
hemodynamic response function to calculate the shape of the predictor as used in the singletrial design matrix.
For a more robust fit of the model, a linear trend confound predictor may be added (next to the
constant predictor and the main predictor) for estimating (and removing) a linear trend by
checking the Linear trend option. The options in the Resulting estimates field allow to specify the
resulting type of single-trial estimate, which can be t values (T-values option), beta values
(Betas option) or percent signal change beta values (Betas (% change)) option. The t values
option is selected as default since it often provides the most robust results. As default, the time
course data within each trial window is z normalized, which can be turned off by un-checking
the z normalization option. In order to exclude voxels in the background (that usually have low
signal values) use the Exclude vals < spin box; to turn this voxel selection filter off, change the
default value of "100" to "0".
The trial estimation process can be started by clicking the GO button. The resulting single-trial
estimates per voxel are stored in slice-based functional map (.FMP) files that are automatically
made available in the Train SVM Classifier tab. For each included time course FMR file, one
corresponding FMP output file will be created.
SVM Classifier Training
The Train SVM Classifier tab (see snapshot above) is used to create SVM training data for a
specified region-of-interest (ROI) from the data listed in the Trial data field (that is created
using the steps described above or loaded from previously stored FMP files). The selected ROI
can be as big as the whole cortex or as small as a few voxels. A typical way to create a ROI is
by using an overall contrast (effects vs baseline) and by dragging a large rectangle
encompassing many (active) voxels. In order to include more voxels, you may lower the
threshold using the Threshold spin box in the right lower corner of the program window. To
increase the number of slices used for ROI selection, you may also want to increase the value of
the MultiSliceROIs spin box; in order to define a ROI across all slices, a large multi-slice value
of e.g. 30 should be used. When entering the dialog, all currently defined ROIs (associated with
respective ROI time course plots) will be listed in the ROI-based feature selection box. If you
have defined more than one ROI, select the one that should be used to specify the features
(voxels) used for training the classifier.
Before the SVM training data can be determined, one needs to specify the classes that should be
used for training in the Selection of classification task field. For a two-class task, you may
select one class in the First class and one class in the Second class selection box. If the FMP
trial response files contain only estimates for two conditions, the class boxes are already filled
with the two class names, respectively. In case that more than two classes are available, select
the relevant classes using the two selection boxes. In the example shown above, three
conditions are used and one of the three possible pairs, "motor_imagery" vs
"mental_calculation" has been selected. For a multi-class task, turn on the Multi-class option;
"mental_calculation" has been selected. For a multi-class task, turn on the Multi-class option;
this will prepare creation of a learning task with all conditions available in the FMP trial
estimation files. Note that it is not possible (in the present version) to select a subset of three
or more classes from four or more available classes: if you want to use more than two classes
but not all available classes, you need to specify the classes in the earlier stage of trial
estimation. Note also that the Multi-class option will only be enabled if at least three conditions
are available. If the option is turned on, the two class selection boxes will be disabled.
When 1) an ROI has been selected for 2) available trial estimation FMP maps and if 3) the
classes for training have been specified, the actual training data for the SVM classifier can be
generated by clicking the Create button in the Create ROI-MVPA data field. The resulting training
data MVP file will appear in the Training/test data text box in the ROI-MVPA data field. The For
training and For testing options in this field are only available to help the user to distinguish the
purpose of a specific training data file. If the For training option is selected (default), the
resulting .MVP training data file will begin with the "Train_" substring whereas it will begin with
"Test_" in case that the For testing option is selected.
The snapshot above shows the ROI-MVPA data field of the ROI-SVM tab after clicking the Create
button using the Multi-class option in the Selection of classification task field. The name of the
resulting training data file reflects which ROI has been used (ROI 1). It also indicates which
conditions are used and how many trials (exemplars) are available for each class. In the
displayed example, the names of the three conditions are shown followed by three values (6)
indicationg that each of the three classes contains 6 trials. Click the Plot button to create a
visualization of the training data.
With the created .MVP training data file (MVP = multi-voxel pattern), a support vector machine
can now be trained. When the Train button is clicked in the Support Vector Machine (SVM) field,
SVM training is performed for the data in the file listed in the Training/test data text field; the
SVM will use default settings including a linear kernel and a value of "1" for the penalty
(regularization) parameter "C". You may also let the program find an optimal C value by running
a cross-validation procedure (turn Cross-validation option on and set an appropriate Folds value)
that uses only the training data (not yet supported, will be available in later release). While it is
possible to select a non-linear kernel using the Kernel combo box in the Support Vector Machine
(SVM) field, it is recommended to stick to the default linear kernel since this allows to interpret
the weight vector of the trained SVM. The training process results in a .SVM file that is stored to
disk and also shown in the Classifier text box (see snapshot above). Note that if one wants to
run another classifier on the same data with different settings, one needs not to re-create the
training data but can directly select the desired MVP file (if already existing) using the "..."
selection button next to the Training/test data text box.
Note that the Log pane in the Test Classifier tab shows additional information about the trial
estimation and SVM learning process. The last information printed in the log will show the result
of applying the trained SVM on the training data itself. This should lead to a accuracy value of
100%. To test the classifier on new data, use the Test Classifier tab for completed run data or,
for real-time applications, the Real-Time SVM Classification dialog that produces incremental
(online) predictions.
Offline SVM Classifier Testing
To test completed run data using the Test Classifier tab of the Multi-Voxel Pattern Classification
dialog, one needs to create the .MVP file for the testing data in the same way as described for
the training data. This includes using the same ROI but selection of different .FMP files. Before
clicking the Create button in the Create ROI-MVPA data field, it is advised to select the For
testing option in order to name the resulting .MVP file as "Test_..." data. For testing, you do not
run the classifier training step but use the previously trained classifier. The previously trained
classifier can be loaded using the "..." browse button on the right side of the Trained classifier
text box. To test the classifier on the data of the loaded run, click the Test on Run Data button.
The prediction results will be printed in the Log pane. In the example above, a 3-class problem
was trained and each line shows two values, the first is the predicted class value (1, 2, or 3 in
this case) and the second value shows the correct label (if available). Since in the snapshot
above the test was performed on the same data used during training, all patterns are (as
expected) classified correctly. Of course, testing should be performed on new data sets. In the
context of BCI applications, testing needs to be peformed on a trial-by-trial basis during online
scanning. For this purpose, the Real-Time SVM Classification dialog can be used.
Note that the data from the test run(s) should match to the previous training run(s), i.e. the
data should be collected during the same scanning session with runs using the same slice
position parameters; furthermore, the same ROI as used during training must be used to create
the .MVP file.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
Real-Time SVM Classification
For BCI applications it is necessary that a classifier can be used incrementally, i.e. on a trial by
trial basis: As soon as enough data points are available to estimate response values for the
voxels used during training, a real-time classifier provides a "guess" (prediction) about the class
to which the actual distributed pattern likely belongs. The Real-Time SVM Classification dialog
allows to run such an online SVM classifier after an appropriate training phase.
The trained SVM classifier needs to be specified using the "..." browse button next to the
Trained classifier text box. Note that real-time classification needs to perform a trial estimation
step as soon as enough data points are available for the next trial. In order to know how trials
have been estimated during training, the program looks for a file called
"SingleTrialGLMSettings.txt" containing the settings used during training. This file is
automatically saved when estimating trial responses for the training data. If the data of the
current run resides in a different target folder than the data used during training, you should
manually copy that file into the current folder, otherwise default settings will be used (that may
or may not reflect the settings during training correctly). The settings that will be used for trial
estimation are printed in the Log pane (see snapshot above).
The online classification also needs to use the same voxels for extracting trial responses as
used during training. In order to get this information, the program looks for a file called
"VoxelsUsedForTraining.txt" containing a list of the coordinates of the voxels used during
training. This file is automatically saved when the training data is created prior to training for a
selected ROI. In addition to this file, a standard .ROI file "VoxelsUsedForTraining.roi" is available
allowing to load the ROI into the main window using the Analysis > Load .ROI Definition File
menu. If the data of the current run resides in a different target folder than the data used during
training, you need to manually copy the "VoxelsUsedForTraining.txt" file into the current folder,
otherwise the classifier will not work. The Log pane will show whether the file was found and
how many voxels are defined in that file.
When all necessary information is available, a click on the Predict button starts the online
classifier. In order to signal that the classifier is enabled, the button text changes to "Predicting"
and the message "Starting incremental prediction..." is printed in the Log pane. Typically the
Predict button is clicked after having started standard real-time processing, i.e. after clicking
the red Record button in the tool bar of the main program window. The classifier can be turned
off any time by clicking the Predict button again; the classifier also stops working if the
currently processed run ends; if the classifier stops, the text of the Predict button will change
back to "Predict" from "Predicting..." and the Log pane will print the message "Incremental
prediction completed."
The running classifier uses the current protocol to retrieve information of the onset and duration
of trials. As soon as all data points are available to estimate a trial response using a GLM,
response values (t, beta or percent change) for all ROI voxels are calculated and submitted as a
test pattern to the classifier. Information about the processed trial as well as the output value
predicted by the classifier is printed within one line in the Log pane. The first line above, for
example, indicates that the first trial is processed at time point 21 since at this point the data
window for the trial that started at time point 9 is complete (with respect to the used trial
duration and post-trial settings). The printed line also shows the duration of that trial (5 time
points) and the condition number (id) of the corresponding condition in the protocol (2). The
final value is the predicted class label (which is "1" for the first trial shown above). In this
example, the protocol assigns the trials to different conditions since the subject was instructed
to perform a specific mental task. Note, however, that the classifier would also work fine in
case that the protocol would define only one condition (e.g. "unkonwn task") since the classifier
only uses the onset and duration information from the protocol but not any information about
the condition to which the trial belongs. In a brain reading paradigm in which the subject freely
may decide which task to perform, the protocol will not contain any specific condition
information and the condition id will be not informative. In case that the subject performs
mental tasks in a prescribed order, a comparison of the condition id with the predicted class can
be used to assess the accuracy (generalization performance) achieved by the classifier for the
new data set.
Notes
The Real-Time Classification dialog does not block other windows. It is, thus, possible to inspect
time courses, switch to different viewing modes, change the t threshold of GLM contrast maps
and so on while the classifier is working. There is also no conflict with the ROI used by the
classifier since the classifier ROI is stored separately from the ROIs used in the main window.
At present the classifier is only used to predict classes when data points are available for a
whole trial window. In case that no protocol is available, the current implementation will not
produce any output; in this case a sliding window approach would be helpful providing output
values at each TR. Such an approach will be made available in an upcoming version.
At the end of a run, all estimated multi-voxel patterns are stored in a .MVP file with the name
"OnlineClassifiedPatterns.mvp"; you may select this file in the Training/test data field in the
Train SVM Classifier tab of the Multi-Voxel Pattern Classification dialog and visualize the
patterns by clicking the Plot button on the right side of the selected .mvp file.
Copyright © Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
Real-Time Independent Component
Analysis
Independent component analysis (ICA) can identify brain activity from functional magnetic
resonance imaging (fMRI) time-series without a priori "temporal" assumptions, i e. with no
detailed information about the experimental design or the expected hemodynamic response
shape and timing, and with only rough knowledge of potentially activated areas in relation to
stimulus processing or brain status changes.
Using a sliding-window approach for real time data preparation, a spatial ICA analysis can be
conveniently restricted to the most recently acquired data. Assuming that both edges of the
window move during the acquisition, both the accuracy and the computational load of the realtime analysis is constant over time, whereas the sensitivity to dynamic changes in brain activity is
maximized.
Real-time fMRI enables one to monitor a subject's brain activities during an ongoing session, but
results are to be delivered within times in the order of one or a few TR(s). In order to deliver ICA
components as fast as possible the deflation scheme of the FastICA algorithm by Aapo
Hyvarinen is exploited. This makes the ICA maps immediately available for selection and display
by the user even if not all possible components have been extracted from the full dimensionality
window data sets. Moreover, it has been demonstrated that the sliding-window FastICA algorithm
can make a real-time ICA analysis perform comparably to a general linear model (GLM) analysis,
without the need of critical settings for the algorithm, provide that the user is focused on relatively
few consecutive slices in the real-time acquisition.
The principal motivation for running a real-time ICA analysis with the real-time ICA plugin is that
no timing information (e. g. a protocol) is to be specified by the user before starting a TBV
session. This opens the possibility of monitoring a non-triggered, non-repetitive and nonstationary neural activity with only mininal spatial prior on the networks involved. The spatial prior
is easily and dynamically defined and updated over time by the user in terms of rectangular
masks including the potential regions of interest (ROI). Moreover, integration of rt-ICA generated
maps in neurofeedback experiments is possible since the plugin can optionally save the
component data to disk.
The next topic describes how to use the real-time ICA plugin.
References
Esposito F, et al. (2003). Real-time independent component analysis of fMRI time-series.
Neuroimage, 20, 2209-2224.
Hyvarinen A. (1999). Fast and robust fixed-point algorithms for independent component analysis.
IEEE Trans Neural Netw, 10, 626-634.
Copyright © Fabrizio Esposito and Rainer Goebel 2011. All rights reserved.
Turbo-BrainVoyager User's Guide
Running the Real-Time ICA Plugin
As is the case for all TBV plugins, the real-time ICA plugin has two separate stages, a
preparation stage and an execution stage. In the preparation stage, all general settings are to be
defined by the user. These will characterize the entire TBV run and can not be changed
dynamically during the execution stage. In the execution stage, the only required user interaction
consists in the dynamic mask definition by which the user draws a rectangular box in the slice of
interest to update the spatial reference used in the component selection. The box should include
the brain region(s) of interest to be used as "seed" to retrieve the ICA component(s) of interest.
Preparation Stage
The plugin can be invoked from the Plugins menu. This immediately starts the preparation stage
showing a Log window and a series of dialogs gathering choices from the user. TBV also
prevents calling any other plugin until the running plugin is dismissed.
The real-time ICA plugin preparation includes the following steps:
1) Setting the first and last slice that will be included in the spatial ICA analysis:
Note: At this stage, the plugin can not check how many slices will be part of the fMRI slab; it is
therefore very important to provide correct values.
2) Setting the length of the moving time window (in time points):
Note (1): This setting strictly depends on the application. In fact, if you, e. g., expect to find (and
want to track over time) regions activated during blocks of, e. g., 15 time points (i.e. 30s if TR=2s),
the suggested default of 25 points is a good choice since you can have both edges of the most
expected activation response included most of the times, whereas windows shorter than 15
points may let you lose tracking of this pattern during the sustained phase of activation. In
contrast, an ideal event-related response or change lasting 20s could require 10-15 points at TR
of 2s. But keep in mind that the plugin doesn't use any model of the response shape and timing,
therefore these considerations and thoughts can only provide an initial guess.
Note (2): This is also the parameter that most affect the performances. Using too many time
points, in relation to the number of slices included, reduce the real-time performances. However,
selecting 2-3 slices and setting a window of 25 points allows similar real-time performances as
for a real-time (whole-brain) GLM on a standard computer.
3) Setting the maximum number of ICA maps to display in real time and the threshold of
the spatial ICA z score:
Note: In contrast to previous ones, these parameters do not affect performances, but only the
display. Normally, the user is interested in seeing the selected component according to the
current dynamic mask specified (see below). There might be circumstances in which the possible
segregation of the activity into more than one component requires tracking more than one among
the best-ranked components. Up to four components can be specified at this stage. To facilitate
display of the component distribution, overlaid on the EPI, T1 anatomy or meshes, a descriptive
threshold is usually specified with values ranging from 2 to 5 (default: 2.5).
4) Step size for component map updating and saving:
Note: Normally, components can be updated each time when a new fMRI volume becomes
available, i. e. at each new time point. Sometimes, typically when longer time windows are used
(substantially slowing down performance), the user may want to not update each time point but,
e.g. after every 2 or 3 time points. Saving the component maps to disk for external use (e.g.
neurofeedback is also optional and should be only included if necessary since it slows down the
operation of the program.
Execution Stage
After the preparation stage, the plugin is in "stand-by" mode, waiting for TBV to start analysis
providing preprocessed (e.g. motion corrected) functional data incrementally to the plugin. The
Log window is also displayed with a summary of the choices made (see snapshot below). You
may want to resize it to better view the presented text information.
When the TBV analysis starts, the plugin starts. This also implies that the plugin maps (and not
the GLM maps) will be shown as default. At any time during real-time analysis you may use the
Show plugin maps option (see snapshot above) to toggle between ICA component maps and
conventional GLM maps (since a GLM analysis is executed concurrently with the ICA analysis).
Please note, however, that the actual computation of the ICA components only starts when
enough time points have been acquired to fill up the first sliding window. From this moment
onwards, components are extracted, ranked and displayed in real time with volume-by-volume
acquisition as in any TBV session.
If the user does not interact with the program, he will see some maps overlaid on the included
slices (see, e. g. the figure below where slices 10, 11 and 12 were included). However, you
normally get random maps and therefore you may probably visualize just noise most of the time:
In order to make an effective selection, a dynamic mask should be drawn by the user. This can
be easily done with the mouse, as shown below:
The consequence will be that from that moment on, a dynamic mask will be used by the plugin
for selecting (and tracking over time) the ICA component (or components) whose maps
maximally correlate (in space) with the mask. The tracking of this component will normally
continue until either the user defines a new mask or until the activity pattern described by this
component changes dramatically the layout with respect to the mask or in case that the
component vanishes.
The following example shows a visual ICA component tracked over time and the dynamic mask
that makes it possible. The contrast window shows the intrinsic ranking of the component, which,
like the map, changes at each time point as a result of the selection. The Log window reports the
spatial correlation coefficient of the template map obtained from the ROI mask and the (ranked)
ICA maps. The time course is obtained from the region within the ROI.
When choosing to display more than one ICA map at a time, it is more convenient to color code
the different ICA maps separately rather than the z scores using the same color range. To switch
color mode, select the Colors Code Contrasts item in the Analysis menu (the term "contrasts"
identifies both GLM maps as well as plugin maps). The snapshot below shows the respective
menu item; as a result, the different ICA maps are shown each in a different color.
Copyright © Fabrizio Esposito and Rainer Goebel 2011. All rights reserved.