User Guide

Release 1.4.1-7595

TVB Team

September 22, 2015

CONTENTS

Overview of TheVirtualBrain

Installing the Application

2.1 TheVirtualBrains interfaces
2.2 Launching the application .
2.3 Configuring TVB . . . . . .
2.4 Uninstalling TVB . . . . .
2.5 Upgrading the Application .
2.6 Removing user data . . . .
2.7 Supported operating systems
2.8 Application requirements .

.
.
.
.
.
.
.
.

5
5
5
6
7
7
7
7
7

Configuring TVB
3.1 Configuring a headless TVB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2 Setting up a client/server configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

9
9
9

Web User Interface of TheVirtualBrain

4.1 User . . . . . . . . . . . . . . . . .
4.2 Project . . . . . . . . . . . . . . .
4.3 Simulator . . . . . . . . . . . . . .
4.4 Analyze . . . . . . . . . . . . . . .
4.5 Stimulus . . . . . . . . . . . . . .
4.6 Connectivity . . . . . . . . . . . .

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

11
11
16
22
44
50
53

Console Interfaces of TheVirtualBrain

5.1 TVB Profiles . . . . . . . . . . .
5.2 Ipython notebook shell . . . . . .
5.3 IDLE shell . . . . . . . . . . . .
5.4 Terminal shell . . . . . . . . . .

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

73
73
73
73
77

A Description of a Complete Dataset

6.1 General Considerations . . . . .
6.2 Parcellation Mask . . . . . . . .
6.3 Connectivity and path length data
6.4 Cortical Mesh . . . . . . . . . .
6.5 Region Mapping . . . . . . . . .
6.6 Head model . . . . . . . . . . . .
6.7 The TVB demonstration dataset .
6.8 Other datasets . . . . . . . . . .

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

79
79
80
81
82
82
82
84
85

TheVirtualBrain Data Formats

7.1 Exchange Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.2 Export Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.3 Import Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

89
90
90
91

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

ii

User Guide, Release 1.4.1-7595

This document provides the most basic tutorial to get the new user started working with TheVirtualBrain,
version 1.0. As TheVirtualBrain will be updated regularly, please check for updates on our web site:
http://www.thevirtualbrain.org.

CONTENTS

User Guide, Release 1.4.1-7595

CONTENTS

CHAPTER

ONE

OVERVIEW OF THEVIRTUALBRAIN

TheVirtualBrain is a framework for the simulation of the dynamics of large-scale brain networks with biologically realistic connectivity. TheVirtualBrain uses tractographic data (DTI/DSI) to generate connectivity matrices
and build cortical and subcortical brain networks. The connectivity matrix defines the connection strengths and
time delays via signal transmission between all network nodes. Various neural mass models are available in the
repertoire of TheVirtualBrain and define the dynamics of a network node. Together, the neural mass models at the
network nodes and the connectivity matrix define the Virtual Brain. TheVirtualBrain simulates and generates the
time courses of various forms of neural activity including Local Field Potentials (LFP) and firing rate, as well as
brain imaging data such as EEG, MEG and BOLD activations as observed in fMRI.
TheVirtualBrain is foremost a scientific simulation platform and provides all means necessary to generate, manipulate and visualize connectivity and network dynamics. In addition, TheVirtualBrain comprises a set of classical
time series analysis tools, structural and functional connectivity analysis tools, as well as parameter exploration
facilities by launching parallel simulations on a cluster.

User Guide, Release 1.4.1-7595

Chapter 1. Overview of TheVirtualBrain

CHAPTER

TWO

INSTALLING THE APPLICATION

To download TheVirtualBrain check out the download site

The TVB software package can be used in 3 different configurations:
on a single machine (personal usage). This machine will need to meet the Application requirements for both
the visualization and the computation/storage part. Any operation launched will use resources from current
machine (graphic card, CPU, disk and RAM).
in a client/server configuration, where TVB is installed on a server and made accessible to an unlimited
number of users.
This configuration is recommended when you have a powerful server to be used as back-end, where TVB
is running and simulation or analysis operations are to be executed. The server machine will not require
powerful graphics, as visualization will not be done here at all. Only the computation requirements from
above will need to be met by the server.
The visualization can be accessed from a personal computers by a browser (via HTTP). A network connection needs to exist between the server where TVB is running and the computer doing the visualization and
access. http://${SERVER-IP}:8080 is the default URL.
using a cluster (similar with server installation, but with parallelization support). Please note that for cluster
installations, OAR is expected to be configured separately from TVB and accessible to the user for which
the TVB software is launched.
To install TheVirtualBrain unzip the package and it will create a folder TVB_Distribution.
TheVirtualBrain developers might need to install TVB differently.

2.1 TheVirtualBrains interfaces

TheVirtualBrain has a web application GUI interface that can be accessed remotely. See the GUI guide for how
to use it.
It also has several flavors of scripting interfaces. These are powerful programmatic interfaces. Unlike the GUI
they are not meant be used remotely and their leaning curve is steeper. See the console interface for usage.

2.2 Launching the application

In the TVB_Distribution folder you should find a sub-folder bin with a number of scripts:
tvb_start
tvb_clean
tvb_stop
contributor_setup
distribution
5

User Guide, Release 1.4.1-7595

ipython_notebook
On Linux these scripts will have the .sh termination, on Mac the .command termination and on Windows the .bat
termination. We will omit the termination in this manual. For example if you are using Windows and tvb_start is
mentioned in this document then tvb_start.bat is meant. The examples below are for Linux.
These scripts will start and control TheVirtualBrain.

2.2.1 Launching the GUI

For Mac users the TVB_Distribution folder contains an application file tvb.app. To start TheVirtualBrain in your
web browser double click tvb.app. Please be patient, as depending on your computer resources, the startup process
might take about 1-2 minutes.
For Linux and Windows users, to start TheVirtualBrain in your web-browser, run the tvb_start script in
TVB_Distribution/bin. On Windows you can double click the scripts icon.
$ cd TVB_Distribution/bin
$ ./tvb_start.sh

To make sure that no processes will remain open after you use the application, you should always close TheVirtualBrain by running the tvb_stop script.
$ ./tvb_stop.sh

2.2.2 Launching scripting interfaces

There are more scripting interface flavors. They differ in what shell is used and in how many TheVirtualBrain
services they use. In the COMMAND_PROFILE interfaces you can use the data management facilities of TheVirtualBrain. In the LIBRARY_PROFILE you use TheVirtualBrain as you would use a library and it will not manage
data for you.
The most user friendly interface is the ipython notebook one. It is a LIBRARY_PROFILE interface. Its shell is
the browser based ipython notebook. To launch it run the ipython_notebook script from the TVB_Distribution/bin/
folder.
$ cd TVB_Distribution/bin
$ ./ipython_notebook.sh

The distribution script is used from a terminal to control the TheVirtualBrain distribution. Run distribution -h too
get help with this command:
$ ./distribution.sh -h

To access the console interface, run in a terminal distribution start COMMAND_PROFILE or distribution start
LIBRARY_PROFILE. A Python IDLE shell will appear. See the console.
$ ./distribution.sh start COMMAND_PROFILE

If you want a plain python text ui shell add the -headless flag to the above commands: distribution start COMMAND_PROFILE -headless This is helpful if TheVirtualBrain is installed on a headless server (no GUI).
$ ./distribution.sh start COMMAND_PROFILE -headless

2.3 Configuring TVB

One of the first actions you will have to perform after starting TheVirtualBrain is to configure it. If you are
installing TheVirtualBrain for personal usage then the default configuration is sensible and you may accept it
without detailed knowledge.

Chapter 2. Installing the Application

User Guide, Release 1.4.1-7595

The default configuration will place TheVirtualBrain projects in a folder named TVB. This folder will be created
in the users home folder.
Linux: /home/johndoe/TVB/
Windows >= 7: c:\Users\johndoe\TVB
Mac : /Users/johndoe/TVB
However for a client server or cluster setup you will need to take some more time to configure TVB. See the
Configuring TVB section for details.

2.4 Uninstalling TVB

To uninstall, stop TheVirtualBrain, then simply delete the distribution folder, TVB_Distribution/ :
$ ./tvb_stop.sh
$ rm -r TVB_Distribution/

This will not remove user data.

2.5 Upgrading the Application

To upgrade to a new version, uninstall the current version then install the new distribution.
Do not remove your TheVirtualBrain projects stored in home_folder/TVB ! The first run after update will migrate
your projects to the new version.

2.6 Removing user data

To purge all user data stored by TheVirtualBrain on your machine run the tvb_clean. It will reset your TVB
database and delete all data stored by TheVirtualBrain. Be careful! Use this to get to a clean state, as if TheVirtualBrain had just been installed and never used.
Note: You do not have to do this to uninstall or update TheVirtualBrain !
$ # This will delete all TVB projects and configuration !
$ ./tvb_clean.sh

2.7 Supported operating systems

The current TheVirtualBrain package was tested on :
Debian Jessie and Fedora 20. Other Linux flavors might also work as long as you have installed a glibc
version of 2.14 or higher.
Mac OS X greater than 10.7 are supported.
Windows XP (x32), Windows Server 2008 (x64) and Windows 7 (x64).

2.8 Application requirements

As TheVirtualBrain redefines whats possible in neuroscience utilizing off-the-shelf computer hardware, a few
requirements are essential when using the software.
2.4. Uninstalling TVB

User Guide, Release 1.4.1-7595

Requirements for front-end visualization:

High definition monitor - Your monitor should be capable of displaying at least 1600 x 1000 pixels. Some
views might be truncated if TVB is run on smaller monitors.
WebGL and WebSockets compatible browser - Weve tested the software on Mozilla Firefox 30+, Apple
Safari 7+ and Google Chrome 30+. Using a different, less capable browser might result in some features
not working or the user interface looking awkward at times.
WebGL-compatible graphics card - The graphic card has to support OpenGL version 2.0 or higher. The
operating system needs to have a proper card driver as well to expose the graphic card towards WebGL.
This requirement only affects PCs, not (somewhat recent) Macs.
Requirements for computation/storage power, dependent on the number of parallel simulations that will be executed concurrently:
CPU power - 1 CPU core is needed for one simulation. When launching more simulations than the number
of available cores, a serialization is recommended. This can be done by setting the maximum number of
parallel threads (in TVB settings) to the same value as the number of cores.
Memory - For a single simulation 8GB of RAM should be sufficient for region level simulations, but 16GB
are recommended, especially if you are to run complex simulations. Surface level simulations are much
more memory intensive scaling with the number of vertices.
Disk space is also important, as simulating only 10 ms on surface level may occupy around 300MB of disk
space. A minimum of 50GB of space per user is a rough approximation.
Optional MatLab or Octave - A special feature in TVB is utilizing functions from the Brain Connectivity
Toolbox. This feature thus requires a MatLab or Octave package on your computer (installed, activated and
added to your OS global PATH variable). The Brain Connectivity Toolbox doesnt need to be installed or
enabled separately in any way, as TVB will temporarily append it to your MatLab/Octave path.

Chapter 2. Installing the Application

CHAPTER

THREE

CONFIGURING TVB

The preferred method to configure TheVirtualBrain is from the web interface. See TVB Settings.
However if TheVirtualBrain is installed on a headless server (no GUI), then the web interface might not be available remotely. See Configuring a headless TVB.

3.1 Configuring a headless TVB

In order to configure TVB in a headless environment, create a file named .tvb.configuration in the home directory
of the current OS user which is launching TheVirtualBrain. Copy the following content and edit it to suit your
needs.
MAXIMUM_NR_OF_OPS_IN_RANGE=2000
URL_WEB=http://127.0.0.1:8080/
ADMINISTRATOR_EMAIL=jira.tvb@gmail.com
MATLAB_EXECUTABLE=/usr/bin/octave
MAXIMUM_NR_OF_THREADS=4
WEB_SERVER_PORT=8080
URL_MPLH5=ws://127.0.0.1:9000/
LAST_CHECKED_CODE_VERSION=6507
USR_DISK_SPACE=5242880
DEPLOY_CLUSTER=False
ADMINISTRATOR_NAME=admin
LAST_CHECKED_FILE_VERSION=2
URL_VALUE=sqlite:////home/tvb_user/TVB/tvb-database.db
ADMINISTRATOR_PASSWORD=[[md5 of password]]
SELECTED_DB=sqlite
MAXIMUM_NR_OF_VERTICES_ON_SURFACE=300000
MPLH5_SERVER_PORT=9000
TVB_STORAGE=/home/tvb_user/TVB

Usually one would change the web server port and domain. TheVirtualBrain will create a folder with project data
named TVB (at the path specified by line starting with TVB_STORAGE). By default it is located in the users home
directory. You can change the TVB_STORAGE to point to a different location.
Finally run the appropriate script for your platform (as described in the previous chapter), to launch TheVirtualBrain with the new settings.

3.2 Setting up a client/server configuration

This is for when you want one TheVirtualBrain instance to service many users via the web interface. In such a
setup the console interfaces of tvb are not available to remote users.
It is likely that you will have to change http ports and the path where TheVirtualBrain will store project data.
Depending on the processing power of the server you might want to adjust the maximum number of operations
threads and vertices. You may also want to adjust the maximum disk quota for each tvb user.

User Guide, Release 1.4.1-7595

In this highly concurrent setup we strongly recommended to use postgreSQL as the metadata storage of TVB.
1. You should install PostgreSQL DB, independently of TVB.
2. Create a database called tvb
3. Choose the postgres user that TVB will use to connect. TVB prefers to connect with the postgres user to
the database but any user with rights over tvb database is ok. ( These are not tvb accounts but db
accounts )
4. Create a db connection URI. Postgres URIs in TVB have this general form
postgresql+psycopg2://postgres:root@[postresql-server-host]:[postgresport]/tvb?user=[user]&password=[postgres-pwd]
The angle bracketed expressions are placeholders that have to be replaced by values specific to your
machine.
5. Place the concrete connection URI in the TheVirtualBrain configuration using either the GUI or by editing
the config file.

10

Chapter 3. Configuring TVB

CHAPTER

FOUR

WEB USER INTERFACE OF THEVIRTUALBRAIN

The workflow of TheVirtualBrain is divided in six major activities. The main menu of the web interface lays at
the bottom of the page. It links to these six activities.
1. In User, the user can manage their account and TheVirtualBrain settings.
2. In Project, the individual projects are managed with all their data and infrastructure.
3. In Simulator large-scale simulations are defined and launched. Analysers and visualizers associated with a
simulation are defined there. Their results, structural and functional data, are shown in panels. Having multiple panels allows having a quick overview of the current TheVirtualBrain model parameters, simulations
and results. We consider the Simulator to be the core of TheVirtualBrain.
4. In Analysis experimental and simulated data can be analyzed.
5. In Stimulus, patterns of spatiotemporal stimuli can be generated.
6. And finally in Connectivity, the user can edit the connectivity matrices assisted by interactive visualization
tools.
The typical workflow within TheVirtualBrain GUI proceeds through these steps:
1. a project is defined and/or selected and user data, (e. g. a connectivity matrix), are uploaded into this project
2. new data is obtained by simulating large scale brain dynamics with some set of parameters
3. results are analyzed and visualized
A history of launched simulations is kept to have the traceability of any modifications that took place in the
simulation chain.

4.1 User
4.1.1 TVB Settings
Once started, TheVirtualBrain should automatically open your default browser and start on the default
http://127.0.0.1:8080/settings/settings. If not, you should manually open your favorite browser from our list of
supported browsers and open the before mentioned URL. This should open up the following settings page:
These are the configurable settings for TheVirtualBrain. Note that the Name of the administrator is the only one
that cannot be changed later on. The others will be accessible afterward from the profile page of the administrator.
These settings are:
Administrator User Name: the name of the administrator. Default value here is admin. Remember it, as you
will need this account for validating other accounts created with Register function.
Password: the password of the administrator. Default value here is pass. Remember it, as you will need it at a
first login. This password can be changed later by clicking the Change password link, from the profile page
(available only after a login).
Administrator Email: the email of the administrator. Emails requesting validations for new users will be sent to
this address. This can be changed by clicking the edit link from the profile page.
11

User Guide, Release 1.4.1-7595

Figure 4.1: Settings Page

Root folder for all projects: this is the root storage for TheVirtualBrain. All your projects will be stored here, as
well as the logging file and the files used as input and output for the backend server. Please provide here a
valid folder path, on a drive which has enough space for storing TVB data. This field will be present on the
settings page later on, but you wont be able to change it. In case you are forced to change this path/folder,
we recommend that you export your existing projects, stop TheVirtualBrain, start it with the clean option
(and configure new folder) and then import your projects back into the system.
Max Disk Size (in MB): Is the amount of disk space that you (as administrator) can specify as the limit for each
user, to occupy with TheVirtualBrain data. When a user exceeds this limit, they are no longer allowed to
run simulations or other operations producing data. When this limit is exceeded, the user will still be able
to visualize their previously created data, and, if desired, to remove data for making space for new results.
For instance:
A default region level simulation with length 1000 ms takes approximatively 1 MB of disk space.
A surface level simulation, with Local Connectivity pre-computed, Raw monitor and length of 10 ms
takes 280 MB.
Default value here is 5GB. We validate upon setup that a value not greater than the available physical disk
free space is specified. In case you later get errors when running simulations (with disk full messages), but
you still have free space on your hard-drive, feel free to come on this settings page and increase this value
of space allocated to TheVirtualBrain.
DB engine: For benchmarking purposes currently supported are sqlite and postgresql databases. You will need to
provide a valid database URL in case you choose postgresql. In the case of sqlite a default tvb-database.db
will always be used. Please take into consideration that when switching to a new database your existing
data will be lost.
Server name: usually the IP of the server that will run TheVirtualBrain. You can also leave it as the default if
you are just running TheVirtualBrain locally.
Cherrypy port: the port used by cherrypy. You need to make sure this port is not used by some other application
otherwise TheVirtualBrain will not start.
Matplotlib port: the port used by matplotlib. You need to make sure this port is not used by some other application otherwise some visualizers will not work.
Deploy on cluster: set true if you want to run TheVirtualBrain on a cluster environment.

12

Chapter 4. Web User Interface of TheVirtualBrain

User Guide, Release 1.4.1-7595

RPC server: if you are not running on a cluster, this will be the port used by the backend server. If Deploy on
cluster is checked this will not be used.
Maximum number of vertices: maximum number of vertices for a surface.
After selecting your desired settings press the Apply button. This will restart TheVirtualBrain with the new settings.
The restart could take a few minutes.

4.1.2 Login
In order to access TheVirtualBrain, you need to have a user account.
There is a single Administrator account in TVB (created when installing the application). Its default user-name
and password are admin and pass (exactly these words). These are the default values, but when you setup
TheVirtualBrain for the first time (section Settings from above) you can specify different values, if wanted. Please
remember what you specify for this Administrator account, as you are the sole responsible for it (TheVirtualBrain
being installed in your own environment we have no control of your storage). With the Administrator account you
will be able to later validate other TVB accounts.

Figure 4.2: TheVirtualBrain login page

4.1.3 Register
If you want to create a new user in TheVirtualBrain, you should register using the corresponding link (available
on the User Login page), which takes you further to the following form:
When the register button is clicked (on the right), an email is sent to ADMINISTRATOR_EMAIL address. It is the
administrators task to validate the new account. The administrator needs to be logged in to validate an account.
Without validation from the administrator, you will not be able to use the new accounts. For details on how
validation is done, see the User Profile section.

4.1.4 User Profile

This area is available after you login and gives you some basic information, such as:
current logged user-name, and his role (left column)

4.1. User

13

User Guide, Release 1.4.1-7595

Figure 4.3: TheVirtualBrain register page

how much disk space is occupied with TVB Data created by current user (left column, Data field)
what version of TheVirtualBrain you are currently running (top of the right column)
a summary of recent changes to TheVirtualBrain software (right column)
availability of updated versions of TheVirtualBrain (when a new version is available, a tooltip will appear
on the top of the User-pages).

Figure 4.4: The User details page (also called User Profile)
You have also functionality on this page:
Manage other users (available on the left column, only when logged with Administrator account), takes you
to a page for validating or invalidating other user accounts (accounts created with the register function)

14

Chapter 4. Web User Interface of TheVirtualBrain

User Guide, Release 1.4.1-7595

access TVB Settings (same settings as in the first setup iof TVB; although some of the fields become readonly after the first setup)
change the password and the email address for current logged user (also links on the left column)
enable or disable Online Help for current user. By Online Help we mean a bunch of question marks spread
all over the application which can display a tooltip when clicked). In case you find the question marks
annoying, feel free to disable them for your user from this page. Some pages will take longer to load when
Online Help is on. You might want to disable it once you feel confident with the interface.
logout function (button on the right side)

Figure 4.5: Users Management Page (available for admin only)

Tip: TVB is a web application, which gets deployed on every computer where TVB_Distribution is downloaded
and tvb_start command is executed. This happens usually in a local environment; which means that the user and
resource management will be done locally, in that instance, and not in a centralised manner.
When TVB is started for the first time, you will see a settings page, where you can define the administrator account
of that TVB instance. Default that is: admin / pass (exactly these words).
If you are using TVB in a single-user manner (not shared with other colleagues), feel free to use only this user
while working with TVB; you do not need to bother with creating/registering other accounts. It is although
recommended for you to change the password and the email address for this administrator account, especially if
you are working in a LAN and your computer is not having a strong firewall.

If you are using TVB in a shared environment (e.g. installed on a server and accessed from remote by multiple
people), you could follow the following steps:
register accounts (optional)
login with administrator
check admins profile page, link Manage other users
in case you havent registered accounts (step 1) you can now create new accounts using the button on the
right
check the validate checkbox for new users that you want active, and click Save to apply (see figure from
previous page)
from this very same page you can also invalidate some old users which you want to no longer be able to use
TVB

4.1. User

15

User Guide, Release 1.4.1-7595

Figure 4.6: Changing current users email address and password

4.2 Project
Projects are the way you organise data and simulations in TheVirtualBrain. They correspond to directories where
related data sets and simulation results are stored.
Information on the currently selected project is always available by clicking on the upper left corner of the interface:
The Project tab provides access to the projects that you have created within TheVirtualBrain. The second level
menu in the top left corner, next to the Project number, allows you to navigate between five main subpages, each
of which is described in more detail in the sections below:
List of All Projects
Basic Properties
Operations
Data Structure
Saved Figures

4.2.1 List of All Projects

This page provides an overview of all the existing projects.
The star column allows you to select the currently active project.
Some columns display basic information such as the id, name and owner of a project. The last column shows an
estimated total size of a project. It is handy when you run out of disk space and want to clean up old big data.
The colored numbers represent the number of completed, in progress, pending, failed and cancelled operations.
The button columns are linking to the Basic properties, Operations and Data Structure pages for the project.
Clicking any will also make that project the current one.
In addition to the list of existing projects, the right hand menu provides a way to:
Create a new project.
16

Chapter 4. Web User Interface of TheVirtualBrain

User Guide, Release 1.4.1-7595

Figure 4.7: The main information about the selected project.

Figure 4.8: The Project second level menu

4.2. Project

17

User Guide, Release 1.4.1-7595

Import an existing project structure (for example, Exported from a colleagues installation of TheVirtualBrain).
Upon first user registration, a default project is created for you:

Figure 4.9: The default Project

4.2.2 Basic Properties

From this page you can export the project or delete it.
Also you can edit the current projects properties. You are directed to this page when you first create a new project:
Note that the project name may not contain spaces.
If there are other users registered in the framework, you can choose to share the project with them by checking
their respective Visible for boxes.
On the right side of the browser there is the Action Column. There are buttons to delete or export the project. The
last two buttons allow you to save changes or go back to the List of All Projects page.
If you were creating a new project it should now be visible.
Warning: Project properties cannot be edited while operations are running!

4.2.3 Image Archive

TheVirtualBrain provides you with the possibility of saving image snapshots.
From this page you can manage all the images stored within the current working Project, as well as:
edit figure title,
create categories to group your images,
18

Chapter 4. Web User Interface of TheVirtualBrain

User Guide, Release 1.4.1-7595

Figure 4.10: The Project Properties page

search through your figure collection,
visualize, download and delete your images.
Note: Only the current project figures will be available. If you want to visualize images from another project,
you will have to switch to that project.

Figure 4.11: The Image Archive page

4.2.4 Operations
A table with the history of operations related to the currently selected project is displayed. From this board the
user can filter, view, reload or cancel any operation:

4.2. Project

19

User Guide, Release 1.4.1-7595

Figure 4.12: The operation page with default operations

4.2.5 Data Structure

This page shows all datatypes of a project in a tree view.
This tree has three levels. Each level groups the datatypes. The first level groups by the state of a datatype, then
each state group is further divided in groups for each subject. The leaf nodes are all datatypes of the project.
You can change the criteria of this grouping. Experiment with the level1 and level2 drop down menus found above
the tree.
Besides grouping the datatypes you may also filter them. The left-most area of the Data Structure page contains
basic filters for the centrally displayed entities. We display fixed filters (entities declared relevant / irrelevant) of
free-text filtering (when using the input text field and then pressing Button Filter). Filtering based on free-text
searches into all fields of an entity, and it is case insensitive.
Note that the color of the datatype icons in the tree view indicate their category:
1. Green are the raw datatypes. These are mostly imported in TVB (eg. connectivities, surfaces, sensors etc.)
2. Yellow are adjacent datatypes. These usually imported in TVB (eg. lookup tables and matrices etc.)
3. Red are time series datatypes either created by simulations or imported.
4. Blue are analyser results.
5. Pink are some datatypes created by TVB (eg. stimuli, local connectivities etc.)
Selecting a data node in the Tree structure causes an overlay to appear.
From this overlay, the user can:
edit metadata
launch Analyzers and Visualizers
link data to other projects
export data.
On the most-right area of this page, an upload button appears. This launches an overlay with tabs for each type of
TVB-compatible data:
For a detailed description of the supported file formats see TheVirtualBrain Data Formats

20

Chapter 4. Web User Interface of TheVirtualBrain

User Guide, Release 1.4.1-7595

Figure 4.13: The data structure of the default project.

Figure 4.14: A data nodes overlay

4.2. Project

21

User Guide, Release 1.4.1-7595

Figure 4.15: The data upload overlay

Launching any uploader with success will generate you a new leaf in the Tree displayed centrally on this page.
The central area also contains a Graph view. The main target for the Graph view is to show you in a mixed manner
both DataTypes and Operations. The edges that link the Graph are of type: Operation generated DataType and
DataType is input for Operation. When switching from the Tree display to the Graph display, the same node (if
DataType) remains selected. This way you could filter entities in the Tree display, check generic meta-data, then
switch to the Graph display and see what Operation was parent for this entity.

4.3 Simulator
A configurable multicolumn interface that combines TheVirtualBrain simulation, analysis and visualization capabilities.

4.3.1 Configure a Simulation

A simulation is configured from the middle column.

On the top of this column there is:
a field to enter the new simulation name,
the Launch button on the top right to start the simulation, and
the Configure Interface button to select which of the simulation components are visible.
links to pages that allow detailed configuration

22

Chapter 4. Web User Interface of TheVirtualBrain

User Guide, Release 1.4.1-7595

Figure 4.16: A graph view of the projects data-structure

Figure 4.17: Preview for Simulator Area

4.3. Simulator

23

User Guide, Release 1.4.1-7595

region model configuration

region noise configuration
surface level configuration (available for surface simulations)

In this column you can change all the configurable parameters of a simulation:
Long Range Connectivity
Long Range Coupling Function
Conduction Speed
Cortical Surface
Stimulus
Local Dynamics Model
State Variable Range
State Variables to be recorded
Initial Conditions
Integration Scheme
Integration Step Size
Monitors
Simulation Length
You can find more detailed information by clicking on the

icon next to each element.

Note: You can filter DataTypes (like Long Range Connectivity) from UI

Click on Add Filter button bellow a DataType

select the attribute to be filtered, the operator to apply and the value in this filter
click Apply Filters to have the results filtered in the selector component right above the filters
this ca also be used in the context of Parameter Space Exploration of TheVirtualBrain

24

Chapter 4. Web User Interface of TheVirtualBrain

User Guide, Release 1.4.1-7595

The Phase plane page

It is used to explore and define parameter configurations. It is accessible from the top menu:

This page allows you to observe how the dynamics of the physical model change as a function of its parameters.
On the left column you select the model you want to explore and set its parameters.
The selected model will generally have a n-dimensional phase space. The right column shows a 2-dimensional
axis cut of this space. Gradients are shown and nullclines if they exist. To control this cut use the Axes and State
variables regions in the left column. There you can select what state variables should be shown and their ranges.
Also you can set values for the variables that are not shown.
If you click in the phase plane a state trajectory will be computed. The integration method for this trajectory is
configured on the left column. To make trajectories longer increase the integration step. This will not influence
the simulation. For stochastic integrators decreasing the dispersion usually makes sense. Below the phase graph
you will see the signals for all state variables. These signals belong to the latest trajectory.
Finally to save a parameter configuration give it a name and click Save new parameter configuration. This saved
configuration can be used in Region-based simulations

Figure 4.18: The phase plane.

Note: TVB performs region-based and surface-based simulations

You can access specific configuration pages for both types of simulation.

4.3. Simulator

25

User Guide, Release 1.4.1-7595

Region-based simulations
The Set up region Model button leads you to the region model page. Here you can associate model parameter
configurations to connectivity nodes.

Figure 4.19: Region model configuration.

The Configure noise button leads to the region noise page. Here you can associate noise dispersions to connectivity
nodes. Select some nodes using any of the selection components or the 3d view. Choose dispersions for all state
variables then place those values in the selected nodes.

Figure 4.20: Region noise configuration.

Surface-based simulations
If you are launching a surface-based simulation, then it is possible to add more complexity by spatially varying
the model parameters.
In order to do that, click on Set up surface model. A new configuration page will be loaded.

Tip: Parameter Space Exploration

It is possible to launch parallel simulations to systematically explore the parameter space of the local dynamics
model. In the current TVB version, up to 2 parameters can be inspected at the same time.

26

Chapter 4. Web User Interface of TheVirtualBrain

User Guide, Release 1.4.1-7595

Figure 4.21: Preview for surface model configuration.

Figure 4.22: The results will be presented in a discrete two dimensional graph. Each point represents the results
of a simulation for an unique combination of parameters. The disk size corresponds to Global Variance and the
color scale corresponds to Variance of the Variance of nodes.

4.3. Simulator

27

User Guide, Release 1.4.1-7595

4.3.2 Simulation History

On the left column, a history of all simulations is kept and can be accessed at any time. Each simulation can be
renamed or deleted by clicking on the upper right

icon.

Figure 4.23: Simulation editing menu

Caution: Please notice that deleting a simulation will also delete all resulting data that had been produced.
Each simulation has a color label that represents its current status:
pale blue: simulation is running,
green: simulation is finished,
red: an error occured during the simulation.
Note: You cannot rename a Simulation while it is running.

Tip: The star button allows you to create a new simulation. using the default Simulator parameters.

4.3.3 Display Simulation Results

On the right column you will find an area where you can configure displays to exhibit your simulation results.
Hint: Maximize this column by clicking on the zoom icon located in the top right corner.
There are 4 tabs:
three View tabs you can set up by selecting:
TVB time-series Visualizers that directly plot the resulting time-series or

28

Chapter 4. Web User Interface of TheVirtualBrain

User Guide, Release 1.4.1-7595

TVB-Visualizers associated with a TVB-Analyzer. In this case, simulation results undergo two steps:
they are first analyzed and those secondary results are shown in a corresponding visualizer.
one Results tab containing the current simulation data structure tree. You can inspect each element through
this tree in the same way as in Projects > Data Structure. A full list of visualizers and analyzers is available
from the component overlay menu.
Tip: Once your results are available, by clicking on

you will be redirected to a new

page where only the currently selected visualizer is presented. In this new page, you can click on
right corner to access a new menu which will allow you to:

in the top

Save a snapshot of the current figure.

Relaunch the visualizer using a different entity, if available. For instance, a different time-series.

Figure 4.24: Preview for Full Visualizer mode.

All the snapshots you save can be managed in Projects > Image Archive page.
orphan

4.3.4 Simple Visualizers

Brain Activity Visualizer
A 3D scene of the brain activity.
Mouse interaction:
You can change the view by pressing a mouse button and dragging it.
the left button rotates the brain around the center of the screen.
the right button translates the brain.
the middle button and the scroll wheel zoom towards the center of the screen.
Pressing the shift key and the left button has the same effect as the right button.
Pressing the control key will rotate or translate in the model space.

4.3. Simulator

29

User Guide, Release 1.4.1-7595

The SPACE key will show a top view. The CURSOR Keys will show axis aligned views.
For region level time series the brain is represented by a coarse granularity - each region is represented with only
one color. For surface level time series each vertex has an individual measure.
The color coding is determined by the current color scheme. A legend of it is on the right side of the brain view.
You can change this color scheme and other viewer parameters from the brain menu in the upper right corner.
From the visualizer toolbar you can pause and resume the activity movie. For region level time series there is a
selection component in the toolbar. Use it to show activity only for the selected regions.

Figure 4.25: Preview for Brain Activity Visualizer at the region level

Time Series Visualizer (svg/d3)

In the center area you click and drag to zoom, click once to reset zoom and use the scroll wheel to scroll signals.
The horizontal bottom part is the temporal context. Here the solid line marks the mean across channels, in time.
The shaded area marks standard deviation across channels, in time. You Click and drag to select a subset of
signals. The selection can be changed again by dragging it. Click outside selection box to cancel and reset view.
You can resize the view by dragging blue box in the bottom right corner.
The vertical left part is the signal context. Here solid lines show each signal. Selection works like in the temporal
context.
In the brain menu there is a slider you use to change the signal scaling.
Animated Time Series Visualizer
This is an alternative for the Time Series Visualizer (svg/d3). It is used to display signal lines in 2D.
The label animated comes from the red line which will pass the entire signal step by step, at a configurable
speed. In single mode, this red-line might not be very useful, but it makes more sense when the same 2D display
gets reused in the Dual Visualizers (combined with the 3D display on a surface) where the red-line shows the
current step displayed in the 3D movie on the left.
Select zoom area with your mouse (you may do that several times to zoom in further). From the toolbar you can
pause resume the activity and zoom out.
This viewer can display multiple time series. On the right side of the toolbar there will be a selection component
for each signal source. These selection components determine what signals are shown in the viewer. To select
30

Chapter 4. Web User Interface of TheVirtualBrain

User Guide, Release 1.4.1-7595

Figure 4.26: Preview for Time-Series Visualizer (svg/d3)

Figure 4.27: Preview for Animated Time Series Visualizer

4.3. Simulator

31

User Guide, Release 1.4.1-7595

additional time series use the brain menu in the upper left corner. From that menu you can change viewer settings.
The page size determines how much data should appear at once in the viewer. The spacing determines the space
between the horizontal axis of each signal. Setting it to 0 will plot all signals in the same coordinate system. A
side effect of this setting is that as you decrease this axis separation the amplitude of signals is scaled up.

Figure 4.28: Selecting the channels to be displayed (available in several viewers of TVB).

Dual Brain Activity Visualizer

This visualizer combines the brain activity movie shown in a 3D display on the left, with the explicit channels
recording lines on the right. Movie start/stop, speed control, color schema change, channel selection are some of
the features available in this visualizer.

Figure 4.29: Brain activity wit EEG recordings.

32

Chapter 4. Web User Interface of TheVirtualBrain

User Guide, Release 1.4.1-7595

Figure 4.30: Brain activity with sEEG recordings (on the left instance) and region level activity (on the right).

Figure 4.31: TimeSeries Volume with selections

4.3. Simulator

33

User Guide, Release 1.4.1-7595

Time Series Volume Visualizer

This visualizer displays time series of volumetric data, like fMRI.
There are 3 navigation and viewing quadrants on the left and one main focus quadrant (left-central). It is possible
to navigate in space using the slide controls on the top-left toolbar or by clicking on the 3 navigation quadrants
on the most left part of the screen. So clicking in the 3 left squares will change the X, Y, Z of the planes slicing
through the currently displayed volume (as the sliders on top are doing), while clicking in the main (central) square
will select the clicked point for display of details on the right.
The playback function is activated by clicking the play button on the top bar, and it will then change the display
with time (left and right areas); The time series data is buffered from the server according to the currently section
of view.
A different color map can be selected by clicked the Brain call-out in the top-right side of the screen.
Time Series Line Fragments
This is the right part of the TimeSeries Volume visualizer and is composed of three main parts:
Global Time Series Graph All selected lines are shown here (top area), with the same scaling. Some transparency
is applied to the lines and only one line is highlighted at a time. Highlighting can be done be passing the mouse
over the line on the global graph or by clicking the selected line in the sortable graphs bellow. Vertical scaling is
done based only on the selected values and not on the complete data set. A red vertical line shows the current time
point (correlated with the movie in TimeSeries Volume section). A blue line follows the mouse showing the value
of the highlighted line at each point.
Time slice selection (focus): This function can be used to display only a portion of the data, zooming on it bellow.
The user can manually define the time slice with the mouse actions ,while it will automatically set itself around
the current time point with a default extent during playback.
Sortable Graphs: Every selected time series from the volume is shown on a separate line and labeled based on its
coordinates from the 3D space. Adding lines in this section can be done by clicking in the left area on the main
quadrant. The lines are colored following the selected feature in Color Lines by at the top of the screen. They
are then sorted automatically by one of the selected methods or manually, by dragging and dropping each line in
the desired position, as seen on the picture bellow. Lines can be removed by dragging them to the top trash bin
area that appear every time a line is selected to be dragged.

Figure 4.32: TimeSeries Fragment

34

Chapter 4. Web User Interface of TheVirtualBrain

User Guide, Release 1.4.1-7595

Connectivity Measure Visualizer

This visualizer can be used for displaying various Brain Connectivity Measures, related to a given Connectivity.
On the X axis, we will see the Connectivity nodes listed, and for each of them, we see the computed measure on
the Y axis.

Figure 4.33: Connectivity Measure Visualizer.

Topographic Visualizer
This visualizer can be used for displaying various Brain Connectivity Measures, related to a given Connectivity.
Its input is same as for the previous visualizer (Connectivity Measure Visualizer), but the display is completely
different. Instead of a discrete view, this time, we can have a continous display (with gradients).

Figure 4.34: Preview for Topographic Visualizer

4.3. Simulator

35

User Guide, Release 1.4.1-7595

Surface Visualizer
This visualizer can be used for displaying various Brain Surfaces. It is a static view, mainly for visual inspecting imported surfaces in TVB. Optionally it can display associated RegionMapping entities for a given surface.
Navigate the 3D scene like in the Brain Activity Visualizer.

Figure 4.35: Surface Visualizer.

Sensor Visualizer
This visualizer can be used for displaying EEG, MEEG, and internal sensors . It is a static view, intended for
visual inspecting imported sensors in TVB. Optionally it can display the sensors on a EEG cap surface.
To show sensors displaying on a Cap, check the call-out on the top-right corner.
When displaying the EEG sensors on a EEG Cap surface, we are automatically computing a parcellation. Currently this parcellation has no anatomical meaning, it is only based on distance (a vertex gets coloured as the
closest sensor).
Navigate the 3D scene like in the Brain Activity Visualizer.
Local Connectivity Visualizer
Once a Local Connectivity dataTypes (which in fact is a huge sparse matrix of max size surface vertices x surface
vertices, shaped after the cut-off) gets computed, one can view the correlation of a given vertex compared to all its
neighbours, by launching this viewer (from the DataType overlay).
In order to see some correlation, one should pick (by mouse click) a vertex on the 3D cortical surface once it loads
in the canvas.
Annotations Visualizer
This viewer shows ontology annotations linked with TVB connectivity regions. It is composed of two main display areas:

36

Chapter 4. Web User Interface of TheVirtualBrain

User Guide, Release 1.4.1-7595

Figure 4.36: Cortical Surface Visualizer with Region Mapping applied.

Figure 4.37: EEG and MEG Sensors.

Figure 4.38: Internal Sensors.

4.3. Simulator

37

User Guide, Release 1.4.1-7595

3D left-side canvas with TVB regions. These regions are color coded, based on the connectivity
region index (similar to Surface Visualizer when a Region Mapping entity is selected). From the most
top-right corner menu, you can change the color scheme used to draw these regions coloring.
2D tree display of ontology annotations. A tooltip will appear if you go with the mouse over various
nodes, and will show you details imported from the ontology.
The two areas (left and right) are linked, both ways:
You can pick a vertex in 3D and have the corresponding tree node highlighted on the right-side, or
backwards:
Click on the tree, and have the corresponding region(s) highlighted in 3D.

Figure 4.39: Pick a vertex in 3D and have the corresponding tree node selected on the right.
Hints:
There is an checkbox on the top-right menu to draw region boundaries in the 3D canvas
When you click on an ontology node on the right, a message text will appear on the top area of the
page, telling you how many TVB regions are linked to this ontology term

Figure 4.40: Select a tree node on the right, and have the linked regions highlighted in 3D.

38

Chapter 4. Web User Interface of TheVirtualBrain

User Guide, Release 1.4.1-7595

4.3.5 Group Display

Discrete PSE Visualizer
Discrete Parameter Space Exploration View, will show up to two measures of the Simulator results, after varying
input Simulator Parameters. The two displayed measures are emphasized in the node shapes and node colors.
When running a range of Simulations in TVB, it is possible to do it by varying up to 2 input parameters (displayed
on the X and Y axis of current viewer).This visualizer supports to display results when the resulting space is not
bigger than 200 points.

Figure 4.41: Preview for Discrete PSE Visualizer, when varying two input parameters of the simulator
When moving with your mouse cursor over a graph node, you will see a few details about that particular simulation
result. When clicking a node, an overlay window will open, which gives you full access to view or further analyze
that particular Simulation result.
Isocline PSE Visualizer
Continuous Parameter Space Exploration View, will show the effect of varying Simulator parameters in a continuous form.
4.3. Simulator

39

User Guide, Release 1.4.1-7595

When running a range of Simulations in TVB, it is possible to do it by varying up to 2 input parameters (displayed
on the X and Y axis of current viewer). This visualizer supports ranges with 2 dimensions only, it does not support
ranges with only one dimension. Also both varying dimensions need to be numeric parameters (no DataType
ranges are supported for display in this visualizer).

Figure 4.42: Preview for Continuous PSE Visualizer, when varying two numeric input parameters of the simulator
Controls for scaling or zooming the graph are available in this viewer. When you click on the coloured area, an
overlay window will open, containing possibility to view or further analyze the simulation result closest to the
point where you clicked.

4.3.6 Analyzers + Visualizers

Covariance Visualizer
Displays the covariance matrix. The matrix size is number of nodes x number of nodes
Cross Coherence Visualizer
Displays the cross-coherence matrix. Axes represent brain nodes. The matrix size is number of nodes x number
of nodes.
Complex Coherence Visualizer
Displays the complex-cross-coherence matrix. Axes represent brain nodes. The matrix is a complex ndarray that
contains the number of nodes x number of nodes cross spectrum for every frequency frequency and for every
segment
This visualizer is very similar with the previous one (Cross Coherence Visualizer).
Cross Correlation Visualizer
Displays the cross-correlation matrix. Similar to the previous three visualizers.

40

Chapter 4. Web User Interface of TheVirtualBrain

User Guide, Release 1.4.1-7595

Figure 4.43: Preview for Covariance Visualizer

Figure 4.44: Preview for Cross Coherence Visualizer

4.3. Simulator

41

User Guide, Release 1.4.1-7595

Figure 4.45: Preview for Complex Coherence Visualizer

Pearson Coefficients Visualizer
Displays the Pearson correlation coefficients matrix.

Figure 4.46: Preview for Pearson Visualizer (MPLH5)

Fourier Spectrum Visualizer

Plots the power spectrum of each node time-series.
Principal Component Visualizer
On the left, the ring plot displays the fraction of the variance that is explained by each component.
On the right, the first ten components are plotted against the brain nodes (variables).

42

Chapter 4. Web User Interface of TheVirtualBrain

User Guide, Release 1.4.1-7595

Figure 4.47: Preview for Fourier Spectrum Visualizer

Figure 4.48: Preview for Principal Components Analysis Visualizer

4.3. Simulator

43

User Guide, Release 1.4.1-7595

Independent Component Visualizer

ICA takes time-points as observations and nodes as variables.
As for PCA the TimeSeries datatype must be longer (more time-points) than the number of nodes. Mostly a
problem for TimeSeriesSurface datatypes, which, if sampled at 1024Hz, would need to be greater than 16 seconds
long.

Figure 4.49: Preview for Independent Components Analysis Visualizer

Wavelet Spectrogram Visualizer

2D representation that shows how the signals wavelet spectral coefficients (frequency) vary with time.

4.4 Analyze
This area offers a set of techniques for data analysis.
The Analyzers in TheVirtualBrain are not always the best implementations of the algorithms in terms of performance, neither are we offering a complete analysis spectrum, because analysis is not considered the focus feature
of TheVirtualBrain and we do not intend to offer a replacement for tools already existent and successful in this
area. We are merely offering some handy tools for people who want to directly process simulation results inside TheVirtualBrain, although the advised long term strategy is to export simulated data from TheVirtualBrain
and analyze it intensively with specialized tools for your area of interest. We advise you not to run our analysis
algorithms with long timeseries, as some might take a lot of time to finish.
The Analysis area has several interfaces that support the following operations for time-series analysis (and not
only):
Cross-correlation of nodes
Fourier Spectral Analysis
Global TimeSeries Metrics
Cross coherence of nodes

44

Chapter 4. Web User Interface of TheVirtualBrain

User Guide, Release 1.4.1-7595

Figure 4.50: Preview for Wavelet Visualizer

Figure 4.51: Current available analyzers

4.4. Analyze

45

User Guide, Release 1.4.1-7595

Temporal covariance of nodes

Principal Component Analysis
Independent Component Analysis
Continuous Wavelet Transform

4.4.1 Cross-correlation of nodes

Compute pairwise temporal cross-correlation of all nodes in a 4D TimeSeries object. Cross-correlation, or normalized cross-covariance, is a measure that quantifies the degree of linear dependence between two time-series.
To calculate the correlation coefficient of all nodes of a given multi-node time-series, simply select the TimeSeries
object from the drop-down list in the Cross-correlation of nodes interface and hit Launch.
The algorithm returns a CrossCorrelation object that contains cross correlation coefficients for all possible combinations of nodes. Results are visualized with the Correlation viewer.

4.4.2 Fourier Spectral Analysis

Compute a fast Fourier transform (FFT) of a TimeSeries object. FFT is an algorithm to compute the discrete
Fourier transform (DFT) and its inverse for a 1 given sequence of values. DFT transforms a function into its
frequency-domain representation, that is, a sum of weighted sinusoids while preserving all of the information
about the original signal. After decomposing the signal, spectrum analysis quantifies the relative amounts of
amplitudes, powers, intensities or phases of a component versus its frequency.
In order to perform a Fourier analysis of your time-series data follow these steps:
Go to the Fourier Spectral Analysis interface and select a Windowing function, you can choose among
hamming, bartlett, blackman and hanning.
Select the time-series.
Select a segment length.
Hit Launch.

4.4.3 TimeSeries Metrics

Calculate one scalar metric to characterize the time-series dataset.

4.4.4 Cross coherence of nodes

Calculate pairwise temporal coherence of all nodes in a 4D TimeSeries object. Coherence analysis, or crossspectral analysis, can be used to estimate how two time series are related in the spectral domain. Cross-coherence
indicates the degree to which amplitude and phase between two signals relate to each other as a function of
frequency.
To calculate the cross-coherence of all nodes of a given multi-node time-series, simply select the TimeSeries object
from the drop-down list in the Cross coherence of nodes interface, select an appropriate measure for data-point
per block, and hit Launch.
The resulting coherence spectrum can be viewed with the Cross coherence visualizer.

46

Chapter 4. Web User Interface of TheVirtualBrain

User Guide, Release 1.4.1-7595

4.4.5 Complex coherence of nodes

To calculate the complex-cross-coherence of all nodes of a given multi-node time-series, simply select the TimeSeries object from the drop-down list in the Complex coherence of nodes interface and hit Launch.
The resulting coherence spectrum can be viewed with the Complex coherence visualizer.

4.4.6 Temporal covariance of nodes

Compute pairwise temporal covariance of all nodes in a 4D TimeSeries object. Covariance resembles the unnormalized correlation coefficient and measures how much two time-series change together.
To calculate the temporal covariance of all nodes of a given multi-node time-series, select the TimeSeries object
from the drop-down list in the Independent Component Analysis interface and hit Launch.

4.4. Analyze

47

User Guide, Release 1.4.1-7595

The algorithm returns a Covariance object that is a 4D-Matrix with the Dimensions {nodes, nodes, 1, 1}. The
resulting covariance matrix can be viewed with the Covariance visualizer.

4.4.7 Principal Component Analysis (PCA)

Compute a PCA of a 4D TimeSeries object. PCA is a computational method for multivariate data analysis that uses
an orthogonal transformation to convert a set of (possibly correlated) variables into a set of linearly uncorrelated
variables called principal components.
To calculate a PCA of all nodes of a given multi-node time-series, select the 4D-TimeSeries object from the
drop-down list in the Principal Components Analysis interface and hit Launch.
The algorithm returns an PrincipalComponents object that is a xD-Matrix with the Dimensions {x,y,z}. The
resulting time-series can be viewed with the Pca viewer.

48

Chapter 4. Web User Interface of TheVirtualBrain

User Guide, Release 1.4.1-7595

4.4.8 Independent Component Analysis (ICA)

Compute a time-domain ICA decomposition of a 4D TimeSeries object. ICA is a statistical and computational
method for separating a multivariate signal into additive subcomponents by maximizing the mutual statistical
independence of source signals.
To calculate a temporal ICA of all nodes of a given multi-node time-series, select the 4D-TimeSeries object from
the drop-down list in the Independent Component Analysis interface and hit Launch.
The algorithm returns an IndependentComponents object that is a xD-Matrix with the Dimensions {x,y,z}. The
resulting time-series can be viewed with the the corresponding ICA viewer.

4.4.9 Continuous Wavelet Transform (CWT)

Compute a CWT of a 4D TimeSeries object. CWT decomposes a signal into wavelets of different frequencies
yielding a time-frequency representation of the signal.
To calculate a CWT of all nodes of a given multi-node time-series, select the 4D-TimeSeries object from the
drop-down list in the Continuous Wavelet Transform interface, specify transformation parameters like:
mother wavelet function
frequency resolution and range
type of the normalization for the resulting wavelet spectrum
Q-ratio
Sampling period of the spectrum
and hit Launch.
The algorithm returns an WaveletCoefficients object that is a xD-Matrix with the Dimensions {x,y,z}. The resulting
spectrogram of wavelet power can be viewed with the Wavelet viewer.

4.4.10 Brain Connectivity Toolbox Analyzers

If you have matlab or octave installed and available through the command line then all the algorithms offered by
Brain Connectivity Toolbox (BCT) can be used directly from TheVirtualBrain interface and the results can later
be displayed in one of our visualizers.
Additional BCT techniques are:

4.4. Analyze

49

User Guide, Release 1.4.1-7595

Degree and Similarity Algorithms

Centrality Algorithms
Distance Algorithms
Modularity Algorithms
Clustering Algorithms
Density Algorithms
For more details, please refer to BCT web site

4.5 Stimulus
Spatio-temporal patterns can be generated to create stimulation patterns.

Figure 4.52: Preview for Stimulus Area. Select the type of stimulus you want to define / inspect

Note: You can build stimuli for region-based and surface-based simulations

4.5.1 Region level stimulus

Edit Stimulus Equations page
On this page we can define a stimulus temporal profile for the connectivity nodes.

On the left column, we have configurable fields that allows us to:

load a preexisting Region Stimulus entity,
enter the name for a new entity and
select the associated Connectivity matrix that will be used to create a stimulus pattern.

50

Chapter 4. Web User Interface of TheVirtualBrain

User Guide, Release 1.4.1-7595

Most importantly, we can select the Temporal Equation that defines the profile and play with its parameters.
On the right column, the stimulus temporal profile is presented, with constant refresh, as the user changes the
Temporal Equation parameters on the left.

From the action bar in the right side you have access to:

Set Region Scaling page (step 2) where you can:

select the nodes to which the temporal stimulus will be applied and
set the scaling value (stimulus strength) for each of the nodes independently.
Click on Save New Stimulus Region button to create the new stimulus entity, but before that, do not forget to
write a name for the new entity in the left column (field Display name).

4.5.2 Surface level stimulus

Edit Stimulus Equations
In the case of a surface level stimulus, besides the temporal profile, you can define the spatial profile of your
pattern as well.

On the left column:

choose a preexisting Surface Stimulus or
enter the name for a new entity and
select the associated Surface datatype.
select the Spatial Equation that describes the spatial spread of the stimulus and set its parameters.

4.5. Stimulus

51

User Guide, Release 1.4.1-7595

Figure 4.53: Preview for node selection in Stimulus on region level

Figure 4.54: Preview for Stimulus Surface equations

52

Chapter 4. Web User Interface of TheVirtualBrain

User Guide, Release 1.4.1-7595

select the Temporal Equation and set its parameters.

On the right column, the stimulus temporal and spatial profiles are presented, with constant refresh, as the user
changes the equation parameters on the left.
From the action bar in the right side you have access to:
Edit Focal Points and View page (step 2) where you are able to select the spatial focal points:
click on the surface, a pin will point you the selected vertex;
click on Add Focal Point button to mark this vertex, an orange arrow will mark the added point;
repeat for each focal point you want added.

Figure 4.55: Preview for selecting the focal points of a Surface Level Stimulus
On the right column you will have the list of the selected focal points. You can delete them independently.
Hint: The spatial pattern will be centered around the focal points.
Finally, click on Save New Stimulus Surface button to create the new stimulus entity; but do not forget to give it
a meaningful name (left column Display name input field).
Regardless if the current Stimulus entity is stored or not yet, you can visualize the evolution of the spatio-temporal
pattern. Click on the

button to launch the animation.

Tip: You can increase the complexity of a stimulus pattern by building on top of one Stimulus entity.
For an example on how to do it, please read the Test Cases in the User Guide document.

4.6 Connectivity
In this area you can edit both types of TVB connectivity objects:

4.6. Connectivity

53

User Guide, Release 1.4.1-7595

Figure 4.56: Preview of a spatiotemporal stimulus animation

long-range connectivity and,
local connectivity.

4.6.1 Long Range Connectivity

This page is split in two columns.

The left View column contains several Long Range Connectivity visualizations:
a 3D view of the nodes and edges
2D Projections of the connectivity graph
Left
Right
Top
a MPLH5 plot of the connectivity weights matrix
a 3D view showing the time evolution of the connectivity matrix
The right column contains the connectivity matrix editor.

54

Chapter 4. Web User Interface of TheVirtualBrain

User Guide, Release 1.4.1-7595

Figure 4.57: Preview for Connectivity Area

Figure 4.58: Large Scale Connectivity configuration page

4.6. Connectivity

55

User Guide, Release 1.4.1-7595

Connectivity Matrix Editor

Figure 4.59: Preview for the Matrix Editor

The matrix editor allows you to :
easily edit the connectivity weights or tract lengths
select a subset of the available nodes
perform basic algebraic operations on that group; and
save the new version as a new connectivity matrix.
The Connectivity datatype will be available in the Simulator area.
Hint: In the Connectivity Editor only one quadrant is displayed at a time. You can select which quadrant is
shown by accessing the quadrant selector button in the upper left corner of the matrix display.
Assuming that the connectivity matrix is sorted such that the first half corresponds one single hemisphere:
quadrants 1 and 4 will represent the intra-hemispheric connections,
and quadrants 2 and 3 will be the inter-hemispheric connections.
You can create a smaller selection using three methods:
1. Click on the Quick-select button and edit the list of node names.
2. Click on the node labels in the matrix to toggle nodes.
3. Use the node selection dropdown by clicking the Select Nodes button.
TVB enables you to save a new Connectivity object by clicking on
TheVirtualBrain Simulator.

. This entity can be used later on in

You can save a particular selection. Click the Select Nodes button and the selection component will be shown.
Enter a name for the selection and click save.
56

Chapter 4. Web User Interface of TheVirtualBrain

User Guide, Release 1.4.1-7595

Figure 4.60: Preview for Quadrant Selection

Figure 4.61: Preview for Quick-select list

Figure 4.62: Preview for Select Nodes list

4.6. Connectivity

57

User Guide, Release 1.4.1-7595

The Weights button opens a menu to perform basic algebraic operations on a group of edges. You can select
multiple nodes from the current connectivity (by default all nodes are selected); thus you will end up with two
sets of nodes: the set of selected nodes and the set of un-selected nodes. These two sets of nodes, determine four
categories of edges:
In > In: are only the edges connecting the nodes of the selected set.
In > Out: are the edges that connect nodes in the selected set (rows) to nodes in the unselected set
(columns).
Out > In: are the edges connecting nodes in the unselected set (rows) to nodes in the selected set (columns).
Out > Out: are edges connecting pair of nodes in the unselected set.

Figure 4.63: Preview for Bulk Operations on edges

Note: Available operations are:
Assignation (set): assigns the given numeric value to all the edges within the set.
Addition (add): adds the new value to the current value in the connectivity weights matrix.
Subtraction (decrease): subtracts the new value to the current value in the connectivity matrix of weights.
Multiplication (multiply): multiplies the current value in the connectivity matrix of weights by the given
numeric value.
Division (divide): divides the current value in the connectivity matrix of weights by the given numeric value.
Click on the Apply weight change button to perform the selected operation on a group of edges.
Example: HOW TO REMOVE INTER-HEMISPHERIC CONNECTIONS
1. Using the Quick select remove all nodes from the right hemisphere.

2. Apply the changes. The selected nodes appear in green.

3. Save the selection to make it easier later.

4. Move to the third quadrant (Q3).

The Connectivity editor will be aware of two sets of nodes: the ones in your selection (green
nodes) and the ones that are not selected (white nodes).
5. Then you can proceed to perform some operations on the edge values.
The four categories of edges in this particular case are:
edges IN-IN: intrahemispheric edges from the left hemisphere.
58

Chapter 4. Web User Interface of TheVirtualBrain

User Guide, Release 1.4.1-7595

Figure 4.64: Node selection

Figure 4.65: Node selection

Figure 4.66: Save node selection

4.6. Connectivity

59

User Guide, Release 1.4.1-7595

Figure 4.67: 3D visualizer zoom-in to show the interhemispheric connections

edges OUT-OUT: intrahemispheric edges from the right.
edges IN-OUT: interhemispheric edges in quadrant 2 (Q2)
edges OUT-IN: interhemispheric edges in quadrant 3 (Q3)
6. Select operation Set(n) for edges OUT-IN, set the value to 0 and then press Apply.

Figure 4.68: Set IN-OUT edges to 0

7. Repeat for edges IN-OUT .

The inter-hemispheric connections are gone. Do not forget to select all the nodes again before
saving your new matrix. To do so click the select all button in the selection dropdown.
8. Save your new matrix

60

Chapter 4. Web User Interface of TheVirtualBrain

User Guide, Release 1.4.1-7595

Figure 4.69: Select all nodes.

Figure 4.70: Save new matrix

9. Once you have your new matrix, you can launch the connectivity visualizers and check that these connections
are not there any more.

Note: TVB is designed to handle connectivity matrices whose values are:

positive real values, meaning that there is a connection, or
zero values, meaning the absence of a connection
Warning:
TVB does not handle unknowns such as NaNs or Infs.
If your connectivity matrix contains negative values, such as -1 values you should either set these values
to zero or an estimated value based on your research assumptions.

Viewers
Connectivity 3D Edges
This connectivity visualizer allows you to see the structural information as a base model part of TVB.
The 3D semi-transparent surface around the connectivity nodes, whether it is the cortical surface or the outer-skin,
is used just for giving space guidance.
You can select an individual node and right-click on it to activate the incoming or outgoing edges.
For each node you can choose a different color to apply to its edges.
4.6. Connectivity

61

User Guide, Release 1.4.1-7595

Figure 4.71: Reload view

Figure 4.72: Preview for Connectivity Viewer 3D Edges

62

Chapter 4. Web User Interface of TheVirtualBrain

User Guide, Release 1.4.1-7595

Figure 4.73: Preview for Connectivity Viewer 3D Edges - Coloring incoming / outgoing edges

Connectivity 2D Viewer
A 2D representation of the connectivity matrix nodes and edges.
There are three main views (projections):
Left sagittal view
Transverse view
Right sagittal view

Nodes are drawn as circles and the connections as lines. Only the selected nodes are shown.
Visualizing Connectivity Measures
The 3D and 2D Views can be used to visualize two ConnectivityMeasure datatypes. These measures can be the
output of a BCT Analyzer. If given, they will determine the size and colors of the nodes in the views.
You can choose these connectivity measures before launching the Large Scale Connectivity visualizer, or from the
brain menu (see tip below).
To display the measures in the 3D view check the Metrics details checkbox. Nodes will be displayed as colored
spheres. The size of the sphere is proportional to the measure labeled Shapes Dimensions. The color comes from
the current color scheme and is determined by the measure labeled Node Colors.

4.6. Connectivity

63

User Guide, Release 1.4.1-7595

64

Chapter 4. Web User Interface of TheVirtualBrain

User Guide, Release 1.4.1-7595

Figure 4.74: Preview for Connectivity 2D Viewer

Figure 4.75: 3D view of a connectivity measure. Node size is defined by the Indegree. Node color is defined by
node strength.

4.6. Connectivity

65

User Guide, Release 1.4.1-7595

To display the measures in the 2D views click the Show all button.
Nodes are draws as circles, their size proportional to the measure labeled Shapes Dimensions. Their color is
determined by a threshold and the measure labeled Node Colors. Nodes with values above the threshold will be
red and those whose value are below the threshold will be green.

Figure 4.76: Preview of 2D Connectivity Viewer (left lateral view). Node size is defined by the Indegree. Node
color is defined by node strength, threshold is 40.

Tip:
If you wish to change:
the color threshold,
the metrics used to define the node features,
the colormap used in the Connectivity Matrix Editor, or
the Connectivity entity
go to the brain menu on the top right corner

Matrix Overview
A 2D matrix plot to have a complete overview of the initially selected weighted connectivity matrix.

66

Chapter 4. Web User Interface of TheVirtualBrain

User Guide, Release 1.4.1-7595

Figure 4.77: Preview for Matrix Overview display

4.6. Connectivity

67

User Guide, Release 1.4.1-7595

Space-Time
This is a three-dimensional representation of the delayed-connectivity structure (space-time) when combined with
spatial separation and a finite conduction speed. The connectome, consists of the weights matrix giving the
strength and topology of the network; and the tract lengths matrix giving the distance between pair of regions.
When setting a specific conduction speed, the distances will be translated into time delays. The space-time visualizer disaggregate the weights matrix and each slice correspond to connections that fall into a particular distance
(or delay) range. the first slice is the complete weights matrix. Click on any of the subsequent slices to see the
corresponding 2D matrix plot.

Figure 4.78: Preview for the space-time display

4.6.2 Local Connectivity

In this page, you can generate the spatial profile of local connectivity that will be used in surface-based simulations.
Local Connectivity editing page
On the lower right of the browser you will have access to different functionalities by clicking on:
Create new Local Connectivity button: to generate the Local Connectivity entity.
View Local Connectivity button: to launch a 3D brain visualizer displaying the spatial profile of the newly
generated entity.
Local Connectivity Viewer
Edit Local Connectivity button: to go back to the main Local Connectivity editing page.
On the right column there is a display showing different estimations of the spatial profile based on the length of :
Theoretical case: is the ideal case.
Most probable case: resolution is based on the mean length of the edges of the surface mesh.
Worst case: resolution is based on the longest edge in the surface mesh.
Best case: resolution is based on the shortest edge in the surface mesh.

68

Chapter 4. Web User Interface of TheVirtualBrain

User Guide, Release 1.4.1-7595

Figure 4.79: The first slice is the full weights matrix

Figure 4.80: Connections that are between 0 and 2.84 ms, for a conduction speed of 9 mm/ms

4.6. Connectivity

69

User Guide, Release 1.4.1-7595

Figure 4.81: Connections that are between 2.84 and 5.68 ms, for a conduction speed of 9 mm/ms

70

Chapter 4. Web User Interface of TheVirtualBrain

User Guide, Release 1.4.1-7595

Figure 4.82: Local connectivity profile estimations.

and the red-dotted vertical line represents the cut-off distance.
The x-axis range is automatically set to two times the cut-off distance.

4.6. Connectivity

71

User Guide, Release 1.4.1-7595

72

Chapter 4. Web User Interface of TheVirtualBrain

CHAPTER

FIVE

CONSOLE INTERFACES OF THEVIRTUALBRAIN

TheVirtualBrain has several flavors of scripting interfaces. These are powerful programmatic interfaces. Unlike
the GUI they are not meant be used remotely and their leaning curve is steeper.
They are a great tool to build a reproducible workflow. The sequence of actions performed in the GUI are recorded
as operations but a python script using the console interface is more detailed and exact.
From these interfaces you also have full access to the APIs of TVB.
The interfaces differ in what shell is used and in how many TheVirtualBrain services they use.

5.1 TVB Profiles

Some of the features of TVB are optional. The GUI uses all of them but the scripting interfaces may select a
subset. Two profiles may be scripted:
In the LIBRARY_PROFILE you use TheVirtualBrain as you would use a library and it will not manage data for
you.
In the COMMAND_PROFILE interfaces you can use the data management facilities of TheVirtualBrain.
Datatypes will be organized in projects and saved in the User/TVB/ folder. You cannot use the web visualizers.

5.2 Ipython notebook shell

The most user friendly interface uses the LIBRARY_PROFILE by default. It differs from the standard ipython
notebook only by having the tvb modules available. See the scripting_demos for examples of how to use this
interface.
Ipython will start in the demo folder. You will see a list of ipython notebooks. These are the notebooks described
in the demos section. With this interface you can run the demos interactively, edit them and create new notebooks.
Click a notebook to open it. Click the new drop-down to create a new one.
Once a notebook is open you can run the command cells by clicking them and pressing the play button. See
ipython notebooks documentation for more details.

5.3 IDLE shell

One console interface of TheVirtualBrain is an IDLE shell. All TVB services except GUI ones are available within
this shell.
Within IDLE you can run a number of scripting demos to show how to build a network model and run a simulation.
To run any demo use the execfile command:

73

User Guide, Release 1.4.1-7595

Figure 5.1: The demo notebooks

Figure 5.2: An open notebook

74

Chapter 5. Console Interfaces of TheVirtualBrain

User Guide, Release 1.4.1-7595

execfile('/home/user/Downloads/TVB_Distribution/tvb_data/tvb/'
'simulator/demos/region_deterministic.py')

The above command should work on Linux and Windows, as long as you replace
/home/user/Downloads/TVB_Distribution with your personal path towards the folder where TVB was
being downloaded. On Mac OS the path is just a little different:
execfile('../Resources/lib/python2.7/tvb/'
'simulator/demos/region_deterministic.py')
execfile('/home/user/Downloads/TVB_Distribution/tvb.app/Contents/Resources/lib/python2.7/tvb/'
'simulator/demos/region_deterministic.py')

Here is an illustration for the above.

Figure 5.3: Run a TheVirtualBrain demo with execfile

Another way to run a script, that also allows to see and edit the code, is opening the file from the File menu. A
new window will pop out. Then select Run Module from the Run menu. The script will be executed.
To work interactively in the Python shell you need a few tvb modules:

5.3. IDLE shell

75

User Guide, Release 1.4.1-7595

Figure 5.4: Run a TheVirtualBrain demo from the Run Menu option

76

Chapter 5. Console Interfaces of TheVirtualBrain

User Guide, Release 1.4.1-7595

from tvb.simulator.lab import *

This will import all the scientific simulator modules as well as some datatypes that wrap important data as the
Connectivity matrix and cortical Surface.

5.4 Terminal shell

If you are using TheVirtualBrain on a headless machine then Python IDLE is not an option. In this scenario TVBs
shell is a simple python console shell. To launch a python terminal in the command profile use
$ ./distribution.sh start COMMAND_PROFILE -headless
Executing distribution.sh
>>>

And in the library profile

$ ./distribution.sh start LIBRARY_PROFILE -headless
Executing distribution.sh
>>>

The scripts are located in the bin folder and they have platform specific terminations.
The distribution script can be used to launch other profiles as well. The WEB_PROFILE will start the web
interface. The following has the same effect as tvb_start
$ ./distribution.sh start WEB_PROFILE

Using the distribution script allows you to give additional options. The -reset option will clean the TheVirtualBrain
folder before starting the web interface
$ ./distribution.sh start WEB_PROFILE -reset

5.4. Terminal shell

77

User Guide, Release 1.4.1-7595

78

Chapter 5. Console Interfaces of TheVirtualBrain

CHAPTER

SIX

A DESCRIPTION OF A COMPLETE DATASET

The primary purpose of The Virtual Brain platform is to simulate whole brain dynamics. A simulation pipeline
has different stages. The most fundamental stage is building a realization of a computational model which we
call a large-scale brain network model. This model is constituted by a set of structural and functional components
linked together, completely creating a particular model of the brain.
The following document is a generic description of what we often call a minimal structural dataset for TVB and
a complete dataset. The aim of this document is to specify the different pieces of data required to derive the
structural skeleton/substrate of a BNM. Hopefully, experts in the field of data acquisition will help us completing
and improving our description.
A complete dataset should:
provide the history of the acquisition/processing protocols (traceability);
be in a standard format to perform analysis with different toolboxes;
have the Minimal Structural Dataset to derive a self-consistent set of files used in TheVirtualBrain. This
minla dataset will permit users to build large-scale brain network models and save their simulated data under
different output modalities (eg, EEG, MEG, fMRI).
increase reproducibility of the results.

6.1 General Considerations

A dataset should be made available on one single place (eg, through XNAT) to ensure traceability and if required
for clinical/privacy reasons, restricted access.
Note: the following definitions are not definitive, if you come across with a better categorization, please let us
know.
Raw Structural Dataset
a collection of files describing a subjects head (eg, structural MRI AND DTI Data)
Structural Dataset
(a collection of T1/T2 weighted MRIscans + DTI data + parcellation )
Minimal (Preprocessed) Structural Dataset
(surface mesh, parcellation, region centres, region mapping, connectivity matrix)
Complete Structural Dataset
in addition to the structures mentioned above, head model surfaces and information about the units
(areas, lengths, connectivity strengths). Info about the EEG/MEG/iEEG sensors if users wish to
compare simulated data to empirical data. Complete Dataset all of the above + functional data (eeg,
rsfMRI, meg)

79

User Guide, Release 1.4.1-7595

In general, all the steps in the processing pipeline should be documented, so its possible to apply the same
treatment to subsequent datasets. Sending pieces of informations in different files without descriptions from
where they came and how they were processed is a bad practice and only detrimental for your own research
project (takes a lot of time and its not reproducible). We cant provide any meaningful help to integrate/check or
validate incomplete datasets.
Ideally, any volumetric data (eg, in NIFTI format), surface data (eg, GIFTI format) or combination thereof (eg,
CIFTI format) should be provided in their RAW format, and if any pre-processing was performed on the raw
data, associated data such as the region centres and parcellation mask should be provided in the same coordinate
system as the cortical mesh (ie, self-consistent dataset). The meaning of the (x,y,z) coordinates depends entirely
on how the volumetric file was generated. It is possible to set any coordinate system you want (native, mni,
talaraich) depending on the processing you apply to your data. A region centre, for example, would be a single
spatial location in 3D. This location is specified by three numbers (x,y,z), these numbers should ideally represent
mm and must be relative to an origin (x=0, y=0, z=0). The same coordinate system means that the origin is in
the same location relative to the head, and that the axis(x,y,z) point in the same direction with the same orientation.

6.2 Parcellation Mask

What is the purpose of the mask?
A brain mask basically covers the standard brain. The mask needs to partition/parcellate the volume of
space containing the head/brain into regions. It can be used to partition the cortical mesh into regions,
consistently with the derived parcellated connectivity matrices. So, for each row in a connectivity
matrix the mask needs to specify a region of space (region of interest). The mask can then be used
to map the thousands of vertices which make up the surface mesh to the hundred or so regions in the
connectivity matrix, that is, each region/row- in-a-connectivity-matrix is associated with hundreds of
vertices in the cortical mesh. So the mask provides a way for us to generate a one to many mapping
(region mapping) from a row in the connectivity matrix to the many vertices of the surface mesh
which lie in that region. This anatomical parcellation is also used to obtain finer parcellations and
further divide the cortical surface into small regions of interest (REF to Zalesky) and distinguish
subcortical structures.
What should be the format?
NIFTI is a standard format for volumetric time-series, and it is widely used in the neuroimaging
commmunity. Originally, NIFTI-1 file format was based on 16-bit signed integers and was limited to
32,767 in each dimension. The NIFTI-2 format is based on 64-bit integers and can handle very large
volumes and matrices. The more recent CIFTI format is compatible with the NIFTI-2 format and it
also has the extension .nii. We encourage to use the NIFTI-1 format (.nii and .nii.gz).I
Note: add references to the libraries and softwares that are available for NIFTI-1 TVB also has
a reader. Not the same case for NIFTI-2 and CIFTI. FieldTrip is the only one providing CIFTI i/o
functionalities.
In the case of a parcellation mask, each voxel contains an integer corresponding to a specific region (numeric
labeling). This means, assuming voxels of 2x2x2 mm, the mask would consist of roughly 100x100x100 (ie, 1
million) voxels. The range of the integer number in each of these voxels should correspond to the number of
regions (or rows ) in the parcellated connectivity matrix. Some voxels may contain no number or say -1, to
specify that that piece of space doesnt belong to a region, for example if it lies outside of the head. These type of
conventions should be specified and documented. A list with the region names/labels and corresponding integer
index should be provided.
How should region labels and names look like provided with the mask?
A region label is a short unique identifier, a region or area name usually refers to a human readable
description. Examples for one region/name would be something like label: RM-TCpol_R / name:
right temporal polar cortex. Ideally, a reference to the original atlas/template should be provided as
well. Notice that the correspondance between integrers values in the parcellation mask and anatomical/human readable labels should be provided if they are not specified in the volume file.

80

Chapter 6. A Description of a Complete Dataset

User Guide, Release 1.4.1-7595

Are region labels essential?

From the point of view of the implementation of The Virtual Brain the labels are essential?
Are region names essential?
The region names on the other hand are primarily a matter of usability, though a very valuable one,
when you want to identify an area that you wish to modify in a simulation (eg, modeling lesions).
Unless a user is an anatomist and acquainted with the labels, then the names are much clearer.
Why is information on cortical vs. subcortical regions needed?
We need a means of distinguishing cortical from subcortical regions within the mask, so that when we
apply the mask to a cortical mesh we dont inadvertently associate parts of the cortex with subcortical
regions in the connectivity matrix. Ultimately a vector of the length of the number of regions is
needed, specifying whether each region is part of the cortex or not. If the labels or names clearly
include this information, that is they clearly state whether they are cortical regions or not, then the
vector could be generated on this basis.
Is the parcellation mask unique?
No. Currently, there are several parcellation being used in the community. NOTE: REF parcellation
papers. One of the main problems is that parcellations are often custom made and subsequently modified, so it becomes very difficult to track the origins. To begin with, we suggest to use parcellation
mask provided by neuroimaging software tools like FSL AAL 90. If you want to use a custom made
parcellation, then it should have the characteristics mentioned above. Also, having the structural raw
data it is possible to derive connectivity matrices from the same dataset, but at different resolutions.
NOTE: (reference to Hagmann and Zalesky).
What is the coordinate system of the parcellation mask?
It depends on how the parcellation mask was obtained. In principle, it should be registered to a standard space such as MNI. This coordinate systems should be consistent with the surfaces coordinate
systems.

6.3 Connectivity and path length data

What is it required to build a connectivity matrix (parcellated connectome)?
Diffusion data, a parcellation mask and probably the white matter surface (in the same space, aligned).
In TVB, we are not providing the tractography tools to create structural connectivity matrices.
Are the tract lengths essential for using TVB?
Yes. The simulations in TVB take into account time delays, and their magnitude is given by the
distance between pairs of regions scaled by the conduction speed.
Are the region centres important?
Yes! If for a reason unbeknown to you, you happen to not have the white matter fibre lengths,
then TVB uses the region centres to compute a tract lengths matrix based on the Euclidean distance
between region pairs. The region centres are merely a list of Cartesian triplets (x,y,z) that specify
the spatial location relative to the consistent coordinate system mentioned above. Each region centre
is just a single point in space, corresponding to the centre of the region. The region itself might be
spatially extended (if we have the cortical surface), and thus not a single point.
What is the parcellated connectome?
This term was introduced by the HCP, and it refers to the connectivity matrix. For TVB a Connectivity
refers to a set of two matrices (of size anatomical regions x anatomical regions ), one with weights
giving the strength of the connections between anatomical regions and a second matrix with the white
matter fibre lengths between regions;

6.3. Connectivity and path length data

81

User Guide, Release 1.4.1-7595

6.4 Cortical Mesh

We encourage to use the MNI brain template (eg, MNI152) to register your subjects data and extract the corresponding cortical surface.
Is the cortical surface essential?
Yes! Strictly speaking, TVB can perform simulations using only a parcellated connectome as spatial
support. From a scientific point of view MODELING THE ELECTRICAL ACTIVITY ON THE
FOLDED CORTICAL SURFACE is one of the most interesting capabilities to exploit in TVB. Modeling work where different output modalities (like EEG and BOLD) are compared need a certain
level of geometrical detail that is not provided by a coarse-grained connectome. While in the field of
macroconnectomics, the parcellated connectome is sufficient (debatable subject, see the paper by Zalesky), the cortical surface is necessary to work with neural field modeling and to account for spatial
inhomogeneities.
The cortical surface, represents the outer surface of the gray matter. Its often called pial surface.
How is a surface represented?
A way of representing 2D meshes embedded in 3D space is by storing two arrays, one for vertices,
and one for triangles. Tha latter is an array with triplets of indices into the first array of vertices. So,
basically a surface mesh is given by a set of vertices (triplets (x,y,z) defining the location of those
vertices). And alternatively, the mesh can be represented by triagle arrays which are indices into the
vertex arrays; three indices for each triangle.
Then there are other attributes that can be derived from these two main arrays, for instance normals. A normal determines the orientation of a vertex.
All vertex-related/derived information is calculated and stored in separate arrays, although
bound to the surface instance they were derived from.
Read more about normals here:
http://user.xmission.com/~nate/smooth.html
Note: and the upcoming publication where surface regularization is explained for the case of the pial
surface.

6.5 Region Mapping

What is the Region Mapping?
The region mapping is just a relationship between the two pieces of data, mapping regions of a
connectivity onto the nodes of a surface simulation, one to many for the vertices of the cortical surface
and one to one for the remaining noncortical regions. NOTE: A region mapping could be between two
connectomes of different resolution (eg, the connectomes presented in Hagmann 998 to 66 regions).
How is the Region Mapping obtained?
Good question!
TODO: Add links to relevant documentation.

6.6 Head model

What is the purpose of the head model
Head: the bucket that contains the brain. The head is often represented as a set of concentric spheres,
in order to compute the electric field or potential on the skin surface (eg, as recorded with EEG
electrodes). The concentric spheres (surfaces) represent the boundaries between the brain and the
skull; the skull and the skin; and, the skin and the air mesh.

82

Chapter 6. A Description of a Complete Dataset

User Guide, Release 1.4.1-7595

What should be the format?

A surface format like GIFTI, or in the same format used for the cortical mesh.
Is the head model essential?
From a scientific point of view, it is essential to compute the lead-field matrices which will project
the neural activity time-series into sensor space (eg EEG). The boundary surfaces are then required
to assist Open MEEG (or any other similar tool like FieldTrip) to generate good forward models for
EEG/MEG)
The surfaces describing a subjects head: skin, skull, cortical surface. See the description below.
A Minimal Structural Dataset For TVB:
All 3D coordinates should be consistent, ie., vertices, parcellation mask, and region centres should be
in the same units, axis orientations, alignment, etc.
A minimally-complete connectivity data set for TVB
should include the following:
Mesh surface for the cortex (regularised, continuous and complete per hemisphere, that is, there should be
no holes in the surface and it should be possible to unambiguously define an inside and an outside, in other
words, each hemisphere should be topologically spherical):
vertices (Cartesian (x,y,z))
triangles (triplets of indices into the vertices array, TRIANGLES, but not generalised polygons)
Parcellation:
Spatial mask, 3D, PROPERLY ALIGNED WITH THE SURFACE, ie coordinates, orientation
should be IN THE SAME SPACE.
Labels for all regions composing the parcellation/connectivity data.
A clear delineation, if not explicit in the labels, between cortical regions and subcortical structures.
Region centres (Cartesian (x,y,z), consistent with surface, mask, etc), for all regions composing the parcellation/connectivity data.
Connectivity (DSI):
Connection strength/s between regions.
Tract length between regions.
Ideally
For a complete structural dataset, we should also have:
Connectivity: mainly Connection strength between regions.
This should include information specifying the directionality. That is, if the data is
provided as a matrix rather than a file format including meta-data such as graphml,
directionality should be clearly and unambiguously specified.
Mesh surfaces for:
inner-skull: boundary between the brain and the skull,
outer-skull: the boundary of between the skull and the skin
outer-skin: boundary surface between the skin and the air (for EEG/MEG monitors)
Basic additional information:
Units: tract lengths, coordinates etc (mm).
Units: strength/weights units, (au) if none.

6.6. Head model

83

User Guide, Release 1.4.1-7595

additional relevant information...

Guidelines to import the data into TVB
Currently we have some guidelines describing what data fields and in which format users can import
different components of a compelte dataset (connectome, surface, sensors, gain matrix for eeg, etc...).
Note: Check the DataExchange chapter of the User Guide manual.

6.7 The TVB demonstration dataset

DISCLAIMER: This dataset was custom made and built to serve the purpose of numerically testing the simulator,
as well as for theoretical exploration. It does have, however, certain issues with regard to biophysical realism and
so shouldnt be used/relied-upon for that purpose. References, where appropiate, are given. Also, this is an open
source project and contributions are greatly appreciated. If you see an error, please leave a comment or make
corresponding modifications [please give proper references and argument your corrections].
The
parcellation
was
chosen
to
be
as
homologous
as
possible
between
Macaque
and
Human.
(See
the
[scalable
brain
atlas
interactive
tool]
(http://scalablebrainatlas.incf.org/main/coronal3d.php?template=PHT00&plugin=CoCoMac))
Weights are primarily CoCoMac exceptions are colossal connections. These are DSI fibre bundle widths
scaled to fill the 0-3 of CoCoMac.
Most colossal connection are missing. Tract-lengths are actual DSI tracts where possible and Euclidean
distance used where explicit DSI/DTI tract- lengths werent available.
Region centres were generated to be consistent with the demo cortical surface.
In the current parcellated connectome all the non-cortical regions were stripped.
The CoCoMac connectivity belongs to a single hemisphere, so the weights matrix is symmetric (weighted
undirected graph), but the DSI was whole brain and so there is probably hemispheric asymmetry in tract
lengths and the cortical surface is hemispherically asymmetric so region centres arent the same for both
hemispheres. (this item is maybe deprecated...)
The default TVB connectivity is a bi-hemispheric hybrid CoCoMac/DSI matrix. Subcortical regions (e.g. thalamus and other subcortical nuclei) are not included in this matrix.
Anatomical labels and names:
A1: Primary auditory cortex
A2: Secondary auditory cortex
Amyg: Amygdala
CCa: Gyrus cinguli anterior
CCp: Gyrus cinguli posterior
CCr: Gyrus cinguli retrosplenialis
CCs: Gyrus cinguli subgenualis
FEF: Frontal eye field
G: Gustatory cortex
HC: Hippocampal cortex
IA: Anterior insula
IP: Posterior insula
M1: Primary motor area
PCi: Inferior parietal cortex
84

Chapter 6. A Description of a Complete Dataset

User Guide, Release 1.4.1-7595

PCip: Cortex of the intraparietal sulcus

PCm: Medial parietal cortex (Precuneus)
PCs: Superior parietal cortex
PFCcl: Centrolateral prefrontal cortex
PFCdl: Dorsolateral prefrontal cortex
PFCdm: Dorsomedial prefrontal cortex
PFCm: Medial prefrontal cortex
PFCorb: Orbital prefrontal cortex
PFCpol: Pole of prefrontal cortex
And more:
PFCvl: Ventrolateral prefrontal cortex
PHC: Parahippocampal cortex
PMCdl: Dorsolateral premotor cortex
PMCm: Medial premotor cortex (supplementary motor cortex)
PMCvl: Ventrolateral premotor cortex
S1: Primary somatosensory cortex
S2: Secondary somatosensory cortex
TCc: Central temporal cortex
TCi: Inferior temporal cortex
TCpol: Pole of temporal cortex
TCs: superior temporal cortex
TCv: ventral temporal cortex
V1: Primary visual cortex
V2: Secondary visual cortex
We have:
An importer for RegionMapping (externally computed);
We need:
At least one, preferably multiple, complete datasets to serve as a default dataset available to users
who cant or arent interested in providing their own. Of specific importance here is the Connectivity
Parcellation Mask, as well as a specification of hemisphere and cortical vs non-cortical regions. If you
are intetrested in contributing a dataset, please contact paupau.
Algorithm for calculating the region mapping, given a coregistered Cortex and ParcellationMask, including an island removal/correction mechanism to deal with the imperfect alignment that will exist,
even with coregistered data, between an individuals cortical surface and the generic parcellation
mask.

6.8 Other datasets

6.8.1 Hagmann
What has been provided/shown :
A 998 ROIs connectome (weights + resampled distances)
6.8. Other datasets

85

User Guide, Release 1.4.1-7595

A mapping to the parcellated connectome of 66 regions.

Label and anatomical names.
Info about the coordinate system: Talaraich.
Whats missing:
The parcellation mask file.
The cortical surface.
The head model.
Permissions:
On request to the authors.

6.8.2 The Human Connectome Project

So far, the most complete datasets available. We aim to integrate some of the datasets provided by the HCP.
Structural connectivity is the fundamental substrate for building large-scale brain network models, and being able
to use these high quality, standardized and equally pre-processed data would be ideal.
However, advanced HCP datasets will be hopefully released next year. The HCP data release does not include
extensively processed connectivity data for individual subjects, but mainly an average dataset. In the current
release, Q3, there are dense (grayordinate-to-grayordinate) functional connectivity datasets based on resting
state fMRI from individual subjects. However, HCP people are still working on improving many of the steps
for generating structural connectivity datasets, based on diffusion imaging and probabilistic tractography. In the
future, they will release probabilistic tractography and dense structural connectome datasets ( perhaps with the
Q4 release, Q3 release was made available on September 20th, 2013)
There are ongoing efforts both within and outside the HCP consortium to generate improved methods of brain
parcellation, especially cerebral cortex. HCP- sanctioned parcellated connectome datasets (based on improved
cortical parcellations) will be made publicly available in the future (no target date announced yet). Once these
(plus the dense connectome datasets) are released, users will be able to generate parcellated connectomes based
on their own preferred parcellation scheme.
They do plan to make a (FieldTrip-compatible) head model available for each subject scanned using MEG.
What they have:
Almost everything: raw, minimally processed and processed data.
Whats missing:
Preprocessed diffusion data (eg, fiber orientation, fiber tracts) and derived structural connectomes and individual based parcellations.
Permissions:
available after agreeing with the privacy and sharing conditions. In principle, datasets can be distributed
as long as we make users sign the terms required by the HCP. I would suggest, once the dense and some
parcellated connectomes are available, to buy the connectome in a box and have a copy in a centralized
storage server so TVB can read these data in.
Brain-mapping softwares:
FreeSurfer: http://surfer.nmr.mgh.harvard.edu/
FSL: http://fsl.fmrib.ox.ac.uk/fsl/fslwiki/
CIVET: http://www.bic.mni.mcgill.ca/ServicesSoftware/CIVET
CARET: http://brainvis.wustl.edu/wiki/index.php/Caret:About
The Human Connectome Toolkit (CMK): http://cmtk.org/
NiPy: http://nipy.sourceforge.net/

86

Chapter 6. A Description of a Complete Dataset

User Guide, Release 1.4.1-7595

MRtrix: http://www.brain.org.au/software/mrtrix/
CAmino: http://cmic.cs.ucl.ac.uk/camino/
BrainVisa: http://brainvisa.info/
MRI Processing/Analysis/Modeling platforms:
SPM: http://www.fil.ion.ucl.ac.uk/spm/
Fieldtrip: http://fieldtrip.fcdonders.nl/
Brainstorm: http://neuroimage.usc.edu/brainstorm/
Data exchange/db platforms:
The Human Connectome Project: http://www.humanconnectome.org/data/
XNAT: http://xnat.org/
Glossary
Space Coordinate systems:
MNI (we encourage to use this one)
Talaraich
ref: http://fieldtrip.fcdonders.nl/faq/how_are_the_different_head_and_mri_coordinate_systems_defined
Atlases:
In order to compare different brains, it is necessary to register them to a common space by using a
template.
See http://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Atlases
Structural Anatomical Parcellations:
Kotter (macaque)
Broadmann
FSL AAL 90
Hagmann (based on Desikan)

6.8. Other datasets

87

User Guide, Release 1.4.1-7595

88

Chapter 6. A Description of a Complete Dataset

CHAPTER

SEVEN

THEVIRTUALBRAIN DATA FORMATS

The purpose of this chapter is to provide some details about the way TheVirtualBrain instance/installation can
exchange data with other TheVirtualBrain instances, or with other applications available in the neuroscience community. Currently, there are several applications that can analyze and record brain activity in different formats,
and one of the goals of TheVirtualBrain is to allow users from different backgrounds to have quick access to their
recorded data.
To achieve this, we have implemented some mechanisms to IMPORT / EXPORT data at different levels and
formats:
Project - As you may know, TheVirtualBrain data is organized in projects and one of the options is to
transfer projects (with attached data) entirely between TheVirtualBrain installations. This mechanism can
be used only between TheVirtualBrain applications, and no other external tools.
Simple Data - This feature allows you to transfer independent data (e.g. surface, connectivity, time series)
between two TheVirtualBrain instances or between TheVirtualBrain and an external application. As you
may note later, depending on the targeted application, data can be exchanged in a custom TheVirtualBrain
format or a commonly used format used in the neuroscience community (e.g. CFF, GIFTI, NIFTI ...)
Warning: During export and import operations TheVirtualBrain does not apply any space transformation, so
users have to ensure their data (especially in case of import) is generated/stored in the same space.
TheVirtualBrains default project contains data in a space where the nose is pointing in the direction of -y and
the left ear in the direction of +x. The space is right handed: +z points up.
Before proceeding with more details about data exchange, it would be helpful to give you an idea how TheVirtualBrain stores its data. Basically there are two major storage areas:
1. Database - where general information/metadata are stored and relation between stored elements (e.g. assignment of data to a project, data metadata - creation date, owner, etc...)
2. Disk - here we store the real data in a HDF5 format (http://www.hdfgroup.org/HDF5). This means that
for each data type (e.g. surface, connectivity, time series) we store on the disk, it is given a folder structure
in an HDF5 / H5 file which contains all data (e.g. vertices, triangles, etc ...). This format has the following
advantages which made it an optimal solution for our product:
can store huge pieces of data and can access it very fast (even random access)
can organize data in a tree structure (groups and leaves)
allows assignment of metadata on every level
is a format agreed upon by the community and can be used/opened with different tools/languages
(Python, Matlab, java, C++ ...)

An important aspect of TheVirtualBrain storage is that each data/datatype has associated a GUID, which makes it
unique on every system where that data exists.

89

User Guide, Release 1.4.1-7595

7.1 Exchange Projects

TheVirtualBrain product can be installed both on a server, to be used concurrent by multiple users, but also as
a standalone application on a desktop/laptop for personal use. Specifically for the second scenario, there was an
important request to allow people to exchange data. So, TheVirtualBrain has a mechanism to export and import
an entire project to another system.

7.1.1 Export Project

Using TheVirtualBrain interface, any user can export their projects in a custom format that can be transferred to
other users.
File Format
Export results are a ZIP file (named: date + project name), containing in a folder structure, all the details about
the project. More specifically, it contains:
A root level XML file with details about the project itself
Folders for each operation performed as part of the project
Operation folder contains an XML file with details of the operation and a set of H5/HDF5 files for each data
type generated during that operation.
Note: each of the H5 files has a structure as described above in TheVirtualBrain Storage section.

7.1.2 Import Project

A project exported on one system can now be imported on another machine. In the projects area, TheVirtualBrain
offers the possibility to import a project packed as ZIP file.
File Format
To import a project, the user has to provide a ZIP with the same structure like the one described above for Export
Project.
Important: The same project cannot be imported multiple times on the same machine, because each project/data
has a unique identifier (GUID).

7.2 Export Data

Using TheVirtualBrain interface, users can view all data types associated with a project and choose to export
individual pieces of data.
The Export Datatype operation results in a file with a format specific to TheVirtualBrain; it is not a
standard format that can be used automatically by other software. This is basically HDF5/H5 format
[http://www.hdfgroup.org/HDF5] which, for each data type, contains both data and metadata. These files can
be easily opened in Python / Matlab / Java / C++ for additional processing.
In case you want to process HDF5 files with Matlab you can find API documentation here:

90

Chapter 7. TheVirtualBrain Data Formats

User Guide, Release 1.4.1-7595

http://www.mathworks.com/help/matlab/ref/hdf5read.html
Note: The HDF5 functionality referenced above was only introduced in Matlab 2011a.
Note: In the future other data formats might be supported as export format from TVB, but for now, the HDF5 is
the only format available at export time.

7.2.1 File Format

As a result of a Simulation or Analyze function, TheVirtualBrain can generate either a data type or a group of data
types. Each of such structures can be exported as follows:
1. if a simple data type is exported, the result is an HDF5 file which has a root node datatype metadata and
leaves the real data.
2. if a data type group is exported, the result is a ZIP file containing:
at root level, an XML file with the details of the operation that generated the data types
a list of HDF5 files, one for each data type included in the exported group. Each file has structure/details as described above in the case of simple data type export. This format applies to any |TVB|
data type.

7.3 Import Data

Probably this is the most important feature of data exchange, since it allows TheVirtualBrain to bring together
data generated independently by other systems/applications and allows its users to perform different analyses on
it and visualize them. Since there is an abundance of formats available for neuroimaging data, TheVirtualBrain
tries to support as many as possible for an improved user experience.
Warning: In case the imported data includes/represents a surface, TheVirtualBrain does an extra check
regarding the number of vertices of that surface. Basically you can not import into TheVirtualBrain a surface
that has more vertices than a MAX value.
This MAX value is defines and can be changed in the Application Settings area, depending on the configuration/performance of your hardware.

7.3.1 Import Data in TheVirtualBrain Format

In correlation with export operations, TheVirtualBrain interface allows import of data in TheVirtualBrain format
that has been exported from other systems. This format applies to any TheVirtualBrain data type. Depending on
the uploaded file format, imported data can be as follows:
File Format
1. If user uploads a ZIP file, the system automatically assumes a datatype group must be imported and then
process the file accordingly. More specifically, it tries to find an XML file, within the ZIP file, describing
the operation(s) that generated the data types and the list of HDF5 files for each datatype.
2. If user uploads a simple HDF5/H5 file, the system assumes that a simple data type is imported and tries to
process the file accordingly. Basically it reads the metadata stored in the root node group and determines

7.3. Import Data

91

User Guide, Release 1.4.1-7595

the data type (e.g. connectivity, time series ...). Based on the detected type of data, the rest of the details are
filled and the object is stored in the database.

7.3.2 Import Volume Time Series from NIFTI-1 Format

NIFTI [http://www.nitrc.org/projects/nifti ] is a standard format maintained by The Neuroimaging Informatics
Technology Initiative (NIfTI) and NIfTI Data Format Working Group and allows the exchange of data with
different meanings (imaging data, statistical values, etc.; stored as vectors, matrix, label set or mesh). NIFTI data
can be stored in <.nii> or <.hdr+.img> files, or any of these in zipped format (<.gz> files).
For the moment, TheVirtualBrain accommodates import of Volume Time Series from NIFTI files.
File Format
For import, TheVirtualBrain users can upload either .nii or .gz files containing NIFTI data in the format specified
by [http://www.nitrc.org/projects/nifti]

7.3.3 Import Sensors

TheVirtualBrain allows users to import data about sensors used for brain imaging. More specifically, TheVirtualBrain supports three types of sensors: EEG, MEG and INTERNAL. During the import process, the user has to
select a file to import and the type of the imported sensors. Based on the selected type, the data from the uploaded
file will be processed accordingly.
File Format
During import, the user might upload either a TXT file or a zipped TXT in bz2 format. This TXT file should
contain data separated by spaces and grouped as follows:
1. each line contains details of a sensor
2. for each sensor there are four or seven columns
first column represents the name / label of the sensor
next three columns represents the position of sensor (x, y, z)
next three columns (if present) represents the orientation of sensor. These are required only for MEG
sensors.

7.3.4 Import Connectivity from ZIP

This feature allows import of connectivity from a ZIP file. The ZIP should contain files with connectivity details
as follows:

92

Chapter 7. TheVirtualBrain Data Formats

User Guide, Release 1.4.1-7595

File Format
ZIP file should include files with the following naming schema and format:
1. If any file name contains weight, it will be considered as the container for connectivity weights and the
parse process expects the following format:
text file containing values separated by spaces / tabs
contains a matrix of weights
any value greater than zero is considered as a connection. You should not have negative values in your
weights file.
2. If any file name contains centres it will be considered as the container for connectivity centers and the
parse process expects the following format:
text file containing values separated by spaces / tabs
each row represents coordinates data for a region center
each row should have at least 4 columns: region label and center position (x, y, z)
a region label is a short unique identifier, for example: RM-TCpol_R
each region centre is just a single point in space, corresponding to the centre of the region
the meaning of the (x,y,z) coordinates depends entirely on how data was generated. It is possible to
specify any coordinate system you want (native, mni, talaraich) depending on the processing
you apply to your data. A region centre would be a single spatial location in 3D. This location is
specified by three numbers (x,y,z), these numbers should ideally represent mm and must be relative to
an origin (x=0, y=0, z=0).
3. If any file name contains tract it will be considered as container for connectivity tract lengths and the
parse process expects the following format:
text file containing values separated by spaces / tabs
contains a matrix of tract lengths
any value greater than zero is considered as a connection. You should not have negative values in your
tract file.
4. If any file name contains orientation it will be considered as container for connectivity center orientations
and parse process expects the following format:
text file containing values separated by spaces / tabs
each row represents orientation for a region center
each row should have at least 3 columns for region center orientation (3 float values separated with
spaces or tabs)
5. If any file name contains area it will be considered as container for connectivity areas and the parse
process expects the following format:
text file containing one area on each line (as float value)
6. If any file name contains cortical it will be considered as container for connectivity cortical/non-cortical
region flags, and the parse process expects the following format:
text file containing one boolean value on each line (as 0 or 1 value) being 1 when corresponding region
is cortical.
7. If any file name contains hemisphere it will be considered as container for hemisphere inclusion flag for
connectivity regions, and the parse process expects the following format:
text file containing one boolean value on each line (as 0 or 1 value) being 1 when corresponding region
is in the right hemisphere and 0 when in left hemisphere.

7.3. Import Data

93

User Guide, Release 1.4.1-7595

7.3.5 Import Surface from ZIP

Using this option, users have the possibility to import a surface from a more human readable format into TVB.
Basically users have to upload a zip file containing surface data and specify what type of surface they upload
(Cortical Surface, Brain Skull, Skull Skin or Skin Air).
File Format
Uploaded ZIP file should contain files with a specified naming schema and format as follow:
1. If any file name contains vertices it will be considered as container for surface vertices and parse process
expects the following format:
this is a space separated values file
each row represents position of a vertex
each row should have three columns (x, y, z as float values)
2. If any file name contains normals it will be considered as container for surface vertices normals and parse
process expects the following format:
this is a space separated values file
each row represents a vertex normal
each row should have three columns (with float values)
3. If any file name contains triangles it will be considered as container for surface triangles and parse process
expects the following format:
this is a space separated values file
each row represents a triangle
each row should have three columns (int values) - each value representing the index of a vertex from
the vertices array. This indices could be ZERO based or not, depending on the source which generated
the surface. This is the user is required to specify this at import time.

There are systems/applications that generate and store surface data in two parts: for left and right side. If this is
the case, the imported ZIP file is expected to contain text files with the same naming and format, but the name
should contain letter r or l at the end of the suffix (e.g. <trianglesl.txt> and <trianglesr.txt>)

7.3.6 Import Surface from wavefront obj

OBJ is a generic 3d geometry format. Many 3d authoring tools can export geometry in this format.

94

Chapter 7. TheVirtualBrain Data Formats

User Guide, Release 1.4.1-7595

File Format
An overview of the OBJ file format can be found on Wikipedia TVB supports only a subset of the specification.
Meaning that only geometry data is considered and accepted forms for faces attributes are: triangles or quads. We
ignore at import time features such as texture coordinates, materials and groups.

7.3.7 Import Surface and TimeSeries from GIFTI

This is a geometry format (http://www.nitrc.org/projects/gifti/) under the Neuroimaging Informatics Technology
Initiative (NIfTI) that allows exchange of brain data (surface, time series, shapes, labels ...). Basically format is
XML based which stores both data and associated metadata in a single file, with .gii extension.
If uploaded .gii file contains a surface (Cortical Surface or SkinAir) during import TheVirtualBrain stores found
vertices / triangles and computes normals for them.
In case .gii file contains a TimeSeries, user will be asked to specify what is the surface for which TimeSeries is
imported. Important to know: number of vertices from imported time series must be the same as the one selected
for surface. Otherwise import procedure will fail.
File Format
This is a standard format, supported by a large community so all details about it and samples can be found here:
http://www.nitrc.org/projects/gifti
Note: At this moment TheVirtualBrain supports only import of data from a single .gii file. It does not handles
cases when metadata is defines in .gii (XML) file and real data in external files.

7.3.8 Import Data from CFF

CFF (Connectome File) is a complex format that tries to put together all data necessary for brain simulations or
analysis. Because of its complexity and lack of support from the community, this format is not used very often.
For this reason, we decided to implement import only of a custom form of CFF, for demo purposes. Support for
CFF import might be removed in the future versions.
The current TheVirtualBrain version includes a set of demo data, housed in a folder that contains two CFF files
which could be imported for testing.
Since CFF is a complex format you can use it for uploading single data (e.g one surface, connectivity, local
connectivity, region mapping) but also you could group multiple such data into a single CFF file.
File Format
For this feature, the user has to upload a CFF file (which is basically a ZIP file) containing a root file <meta.cml>
which describes the content of the archive. This file specifies what data types are packed (e.g. connectivity,
surface, region mapping) and which files contain data for these types. In our demo data, files are in different
formats: starting from raw data (numpy dump), GIFTI, NXGPickle.

7.3. Import Data

95

User Guide, Release 1.4.1-7595

7.3.9 Import Region Mapping

A Region Mapping in TheVirtualBrain is a vector, defining a map between a Cortical Surface and a Connectivity.
At import time, you will need to have at least 2 entities in TheVirtualBrain system: Connectivity and Cortical
Surface. The two entities need to be spatially aligned (overlap correctly in 3D space).
File Format
For this upload we expect a text file (possibly compressed with bz2). The text file should have no headers, only
numeric values separated with spaces.
The file is expected to hold a vector of length number of vertices in the Cortical Surface. The numeric values
should be in the interval (0...n-1), where n is the number of regions in the connectivity.

7.3.10 Import Projection Matrix

A Projection Matrix, is intended to define a mapping from a source object and a set of sensors. The source entity
can be either a Cortical Surface or a Connectivity, in TheVirtualBrain. In order for this import to work, you will
need to have previously imported in TheVirtualBrain: both the source and the sensors entities.
File Format
For this upload we expect a single text file, with numeric values, space and line separated. The numeric values in
the uploaded file should hold a matrix of size (n, m). n is the number of sensors, and m is the number of nodes.
When the projection matrix we want to import is a Surface Projection Matrix, m will be the number of vertices in
the target Cortical Surface. When the projection matrix is a region-level one, m will be the number of regions in
the Connectivity. Having headers in the text file is not accepted. An incorrect number of values (lines or rows) in
the Projection Matrix will also raise an exception.
Copyright notice
Note: TheVirtualBrain is a brain-simulation software. See also http://www.thevirtualbrain.org
2012-2013, Baycrest Centre for Geriatric Care (Baycrest)
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public
License version 2 as published by the Free Software Foundation. This program is distributed in the hope that it
will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License (GPl_LICENSE.TXT) for
more details.
CITATION:
When using The Virtual Brain for scientific publications, please cite it as follows:
Paula Sanz Leon, Stuart A. Knock, M. Marmaduke Woodman, Lia Domide, Jochen Mersmann, Anthony R.
McIntosh, Viktor Jirsa (2013) The Virtual Brain: a simulator of primate brain network dynamics. Frontiers in
Neuroinformatics (7:10. doi: 10.3389/fninf.2013.00010)

96

Chapter 7. TheVirtualBrain Data Formats