User Guide

Release 2.3-16437

TVB Team

June 25, 2021

 CONTENTS

1 Overview of TheVirtualBrain 3

2 Installing the Application 5

2.1 TheVirtualBrain‘s interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2 Launching the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.3 Configuring TVB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.4 Uninstalling TVB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.5 Upgrading the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.6 Removing user data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.7 Finding TVB Demo Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.8 Supported operating systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.9 Application requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

3 Configuring TVB 11
3.1 Configuring a headless TVB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.2 Setting up a client/server configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.3 Installing PosgreSQL on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

4 Web User Interface of TheVirtualBrain 13

4.1 User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.2 Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.3 Simulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.4 Analyze . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
4.5 Stimulus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
4.6 Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

5 Console Interfaces of TheVirtualBrain 79

5.1 TVB Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
5.2 Ipython notebook shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
5.3 Terminal shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

6 A Description of a Complete Dataset 83

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

7 TheVirtualBrain Data Formats 93

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

i
8 Copyright notice 101
8.1 CITATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

ii
 User Guide, Release 2.3-16437

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 1
User Guide, Release 2.3-16437

2 CONTENTS
 CHAPTER

ONE

OVERVIEW OF THEVIRTUALBRAIN

TheVirtualBrain is a framework for the simulation of the dynamics of large-scale brain networks with biologi-
cally 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, manip-
ulate 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.

3
User Guide, Release 2.3-16437

4 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 connec-
tion 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 TheVirtualBrain‘s 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
• distribution
• jupyter_notebook

5
User Guide, Release 2.3-16437

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.

Figure 2.1: Access error when launching TVB on Mac

On the latest versions of MacOS, you should allow from Settings –> Security and Privacy the newly downloaded
executable to run.
For Linux and Windows users, to start TheVirtualBrain in your web-browser, run the tvb_start script in
TVB_Distribution/bin. On all platforms you can also double click the script’s 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 TheVirtu-
alBrain by running the tvb_stop script.
$ ./tvb_stop.sh

Note: The first time you configure TVB, it will write a file .tvb.configuration in your user home folder. In case
you run into problems when this write is about to happen, you can set environment variable TVB_USER_HOME
to a value more appropriate for your environment (for example pointing towards TVB_Distribution unzipped
location). Specify a value for the environment variable TVB_USER_HOME in distribution command file to have
it ready for multiple TVB runs.

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 TheVir-

6 Chapter 2. Installing the Application

 User Guide, Release 2.3-16437

Figure 2.2: Give access to TVB on Mac

tualBrain. 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 Jupyter notebook one. It is a LIBRARY_PROFILE interface. It’s shell is
the browser based jupyter notebook. To launch it run the jupyter_notebook script from the TVB_Distribution/bin/
folder.
$ cd TVB_Distribution/bin
$ ./jupyter_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 shell will appear.
$ ./distribution.sh start COMMAND_PROFILE

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.
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

2.3. Configuring TVB 7

User Guide, Release 2.3-16437

• 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 TheVirtu-
alBrain 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

The above operation will not touch TVB_Distribution, which represents your downloaded TheVirtualBrain app,
but only TVB generated user data, as result of using the GUI interface, mainly.

2.7 Finding TVB Demo Data

We keep TheVirtualBrain demo data versioned on Github: https://github.com/the-virtual-brain/tvb-data. There
you can find a Default TVB Project, structural Connectivity, Surfaces, Mappings, Sensors, etc.
TheVirtualBrain application comes with a subset of this demo-data, which can be found inside TVB_Distribution
under the following path:
• On Windows TVB_Distribution/tvb_data/Lib/site-packages/tvb_data/
• On Linux TVB_Distribution/tvb_data/lib/python3.x/site-packages/tvb_data/
• On Mac TVB_Distribution/tvb.app/Contents/Resources/lib/python3.x/tvb_data/

Note: Everything under TVB_Distribution is not to be removed or edited.

The files under TVB_Distribution/..../tvb_data and the git repository tvb_data, can be used together with the GUI
and/or the script interfaces, or taken as reference by you, when creating TVB compatible dataset.

2.8 Supported operating systems

The current TheVirtualBrain package was tested on :

8 Chapter 2. Installing the Application

 User Guide, Release 2.3-16437

• Debian Stretch. Other Linux flavors might also work as long as you have installed a glibc version of 2.14 or
higher.
• Mac OS X 10.13 High Sierra.
• Windows 10 and Windows 8.

2.9 Application requirements

As TheVirtualBrain redefines what’s possible in neuroscience utilizing off-the-shelf computer hardware, a few
requirements are essential when using the software.
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 compatible browser - We’ve tested the software on the latest versions of Mozilla Firefox, Ap-
ple Safari and Google Chrome. 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 exe-
cuted 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 doesn’t need to be installed or
enabled separately in any way, as TVB will temporarily append it to your MatLab/Octave path.

2.9. Application requirements 9

User Guide, Release 2.3-16437

10 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 avail-
able 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
[email protected]
MATLAB_EXECUTABLE=/usr/bin/octave
MAXIMUM_NR_OF_THREADS=4
WEB_SERVER_PORT=8080
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
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 TheVirtual-
Brain 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.
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. For Windows user, see the next chapter on how
this can be easily achieved.
2. Create a database called tvb, in PostgreSQL

11
User Guide, Release 2.3-16437

3. Choose the postgres user that TVB will use to connect. Any user with rights over tvb database is ok. These
are not tvb accounts but db accounts.
4. Create a DB connection URI. Postgres URI’s in TVB have this general form
postgresql+psycopg2://postgres:root@[postresql-server-host]:[postgres-port]/tvb?user=[user]&p
# The angle bracketed expressions are placeholders that have to be replaced by values specifi

5. Place the concrete connection URI in the TheVirtualBrain configuration using either the GUI or by editing
the config file.

3.3 Installing PosgreSQL on Windows

Getting PostgreSQL database up and running isn’t too difficult on Windows:
• Grab a copy for 32 or 64 bit from http://www.enterprisedb.com/products-services-
training/pgdownload#windows
• Install, noting the port number and user/pass. These will be later on needed in TVB, when writing the
connection URL
• [optional when using TVB Git repositories directly]
– pip install psycopg2, with the PATH set correctly for your Python installation, or
– grab and install from http://www.lfd.uci.edu/~gohlke/pythonlibs/#psycopg
– test python -c “import psycopg2”, if ImportError, find libpq.dll (e.g. c://program
files/postgresql/9.3/bin) and add it to the PATH.
• open pgAdmin, right click databases, add a database named tvb, click ok, close pgadmin
• stop, clean (this deletes all tvb previous data!) and start.
– This cleanup is necessary if you have started TVB Distribution before and used sqlite DB.
– in case you have important TVB data that should not be lost, you can always use Project Export,
clean, restart, and then Project Import after the new DB backend has been set up.
• in TVB GUI settings page, select postgresql, edit the port number (if not default 5432) and DB password in
the DB connection URL
• validate db (by using the GUI button). It should be ok, if not: look at the output in terminal to see more
details.

12 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 mul-
tiple 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.
The TVB EduPack on the TVB main website contains several video lectures guiding you step by step through
TVB’s web interface:
• LEARN: How to interact with the GUI and script interface of TVB, lecture by Paula Prodan & Mihai Andrei
• LEARN: Hands-On: Introduction to the GUI, lecture by Paul Triebkorn

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.

13
User Guide, Release 2.3-16437

Figure 4.1: Settings Page

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.
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 won’t 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.
Deploy on cluster: set true if you want to run TheVirtualBrain on a cluster environment.

14 Chapter 4. Web User Interface of TheVirtualBrain

 User Guide, Release 2.3-16437

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
administrator’s 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)
• 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)

4.1. User 15
User Guide, Release 2.3-16437

Figure 4.3: TheVirtualBrain register page

• 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)
• access TVB Settings (same settings as in the first setup of TVB; although some of the fields become read-
only after the first setup)
• change the password and the email address for current logged user (also links on the left column)

16 Chapter 4. Web User Interface of TheVirtualBrain

 User Guide, Release 2.3-16437

• 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: User’s 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.

Figure 4.6: Changing current user’s email address and password

4.1. User 17
User Guide, Release 2.3-16437

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 admin’s profile page, link Manage other users
• in case you haven’t 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.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 inter-
face:

Figure 4.7: The main information about the selected project.

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

18 Chapter 4. Web User Interface of TheVirtualBrain

 User Guide, Release 2.3-16437

• Basic Properties
• Operations
• Data Structure
• Saved Figures

Figure 4.8: The Project second level menu

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.
• Import an existing project structure (for example, Exported from a colleague’s installation of TheVirtual-
Brain).
Upon first user registration, a default project is created for you:

4.2.2 Basic Properties

From this page you can export the project or delete it.
Also you can edit the current project’s properties. You are directed to this page when you first create a new project:

4.2. Project 19
User Guide, Release 2.3-16437

Figure 4.9: The default Project

Figure 4.10: The Project Properties page

20 Chapter 4. Web User Interface of TheVirtualBrain

 User Guide, Release 2.3-16437

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,
• 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.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.

4.2. Project 21
User Guide, Release 2.3-16437

Figure 4.12: The operation page with default operations

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
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.

22 Chapter 4. Web User Interface of TheVirtualBrain

 User Guide, Release 2.3-16437

Figure 4.13: The data structure of the default project.

Figure 4.14: A data nodes overlay

4.2. Project 23
User Guide, Release 2.3-16437

Figure 4.15: The data upload overlay

Figure 4.16: A graph view of the project’s data-structure

24 Chapter 4. Web User Interface of TheVirtualBrain

 User Guide, Release 2.3-16437

4.3 Simulator
This page shows a configurable multicolumn interface that combines TheVirtualBrain simulation, analysis and
visualization capabilities.

Figure 4.17: Preview for Simulator Area

4.3.1 Simulation History

We call History the most left column on the Simulator page. Along with the History title, you can observe two
buttons on the top bar of this column.

The button allows you to initialize a new simulation, using the default Simulator parameters. This default
initialization is already happening, if you just landed on this page for the first time. The button can be useful in
case you started configuring a complex simulation and you lost track of the changes, to return to the safe defaults.
The button allows you to upload a JSON file. This file can be exported from a previously configured and
run simulation (on the same or different TVB installation, as long as versions are compatible). Details on how to
export such a JSON file can be found just bellow, when we explain the icon.
As main content in this left column, a history of all simulations is kept and can be accessed at any time.
Each simulation execution has a color label that represents its current status:
• pale blue: simulation is running,
• green: simulation is finished,
• gray: simulation has been canceled by the user,
• red: an error occurred during the simulation.

Each simulation can be renamed, copied, exported or deleted by clicking on icon, next to its name.

To rename a simulation, click the icon first, then edit the text in the input field, and do not forget to press
icon when you are done writing.

Note: You cannot rename a Simulation while it is running, but instead you could cancel it (e.g. if you see it eats
too many of your machine resources, or you simply changed your mind about this run).

4.3. Simulator 25
User Guide, Release 2.3-16437

Figure 4.18: Simulation editing menu

Copy simulation means loading in memory the same configuration, as used for that particular simulation. It will

be your job to optionally change something in the configuration and, when done, press the icon, to actually
run this copy of the simulation.
Export JSON is a new feature which allows you to create a text file, which stores the current simulation parameters.
This text file will be downloaded from your browser window, and can be reused later. You could use it on the same
TVB installation, or on a totally different TVB server, in several manners:
• from web GUI, using the button, on this page (top of column History)
• in the python console of TVB, for better debugging capabilities. Examples for this later case can be found
in the set of examples for COMMAND and LIBRARY profiles.

Caution: Please notice that deleting a simulation will remove the parameters configuration, and also
delete all resulting data that had been produced in relation to that simulation.

4.3.2 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

26 Chapter 4. Web User Interface of TheVirtualBrain

 User Guide, Release 2.3-16437

– 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 Time Series) 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 can also be used in the context of Parameter Space Exploration of TheVirtualBrain

4.3. Simulator 27
User Guide, Release 2.3-16437

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 it’s 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.19: The phase plane.

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

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

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.

28 Chapter 4. Web User Interface of TheVirtualBrain

 User Guide, Release 2.3-16437

Figure 4.20: 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.21: 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.

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.

4.3. Simulator 29
User Guide, Release 2.3-16437

Figure 4.22: Preview for surface model configuration.

Figure 4.23: 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.

30 Chapter 4. Web User Interface of TheVirtualBrain

 User Guide, Release 2.3-16437

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
– 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 in the top right corner to access
a new menu which will allow you to:
• 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.

4.3. Simulator 31
User Guide, Release 2.3-16437

Pressing the control key will rotate or translate in the model space; while without control key pressed, the rotation
happens in the space of the navigator (with center in (0,0,0) ).
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
additional time series use the brain menu in the upper left corner. From that menu you can change viewer settings.

32 Chapter 4. Web User Interface of TheVirtualBrain

 User Guide, Release 2.3-16437

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

Figure 4.27: Preview for Animated Time Series Visualizer

4.3. Simulator 33
User Guide, Release 2.3-16437

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 with EEG recordings.

Volume Visualizer
This family of viewers display volumetric data, usually in an anatomical space. If the data has a time component
then on the right side it will display timelines for selected voxels. FMri data is an example of this. A structural
mri volume may be used as a background.
Volumetric fragment

34 Chapter 4. Web User Interface of TheVirtualBrain

 User Guide, Release 2.3-16437

Figure 4.30: Brain activity with sEEG recordings.

Figure 4.31: Brain activity with region level activity.

4.3. Simulator 35
User Guide, Release 2.3-16437

Figure 4.32: Time Series Volume with selections

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 crosses designate the selected voxel. It’s value is shown at the bottom of the focus quadrant. A white bar on
the color legend also indicates this value.
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. You might
want to use the trim middle values feature with this viewer. It renders values around the mean transparent in the
view. Also to be found on the Brain call-out.
Time Series Line Fragments
This is the right part of the TimeSeries Volume visualizer and is composed of other sub-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 by 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. Try dragging in this region.
The grey selection box can be moved and resized. If the focused data looks flat, increase the selected window
length. The selection 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.

36 Chapter 4. Web User Interface of TheVirtualBrain

 User Guide, Release 2.3-16437

Figure 4.33: Time Series Volume Line Fragments

Display multi dimensional time series:

In case the Time Series displayed comes from a TVB simulation, when the Neuronal Mass Model supports mul-
tiple modes and state-variables, then it is necessary to choose what to display, as this viewer can only show 2D
results. To choose from Mode and State Variable dimensions, a selector will appear on the top-right area. When
changing the selection, the coloring for the left-side volume regions will change accordingly.

Figure 4.34: Time Series Volume - select when multiple dimensions

Already selected Time series lines on the right, will remain unchanged, when Mode and State Variable change,
but if you click again on the left side volume, new lines will be added, for the currently active Mode and State
Variable. One can inspect in the line title, the details for that point (including X, Y, Z position in the volume, full
region name, Mode and State Variable).
Important notice:
While these time lines share the temporal axis they do not share the vertical one. The signal amplitudes are
dynamically scaled so as to make the signal features visible. Amplitudes are not comparable among two of these
signals.
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
appears every time a line is selected to be dragged.

Connectivity Measure Visualizer

This visualizer can be used for displaying various Brain Connectivity Measures, related to a given Connectivity.

4.3. Simulator 37
User Guide, Release 2.3-16437

Figure 4.35: Time Series Volume - Line title

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.

Topographic Visualizer
This visualizer can be used for displaying various Brain Connectivity Measures, related to a given Connectivity.
Its input is the 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).

Surface Visualizer
This visualizer can be used for displaying various Brain Surfaces. It is a static view, mainly for visual inspect-
ing 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.

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”. Cur-
rently 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. The Local Connectivity viewer can be launched from the DataType over-
lay (after clicking on a Local Connectivity datatype, and then selecting TAB Visualizers), or from Connectivity

38 Chapter 4. Web User Interface of TheVirtualBrain

 User Guide, Release 2.3-16437

Figure 4.36: Connectivity Measure Visualizer.

Figure 4.37: Preview for Topographic Visualizer

4.3. Simulator 39
User Guide, Release 2.3-16437

Figure 4.38: Surface Visualizer.

Figure 4.39: Cortical Surface Visualizer with Region Mapping applied.

40 Chapter 4. Web User Interface of TheVirtualBrain

 User Guide, Release 2.3-16437

Figure 4.40: EEG Sensors.

Figure 4.41: MEG Sensors.

Figure 4.42: Internal Sensors.

4.3. Simulator 41
User Guide, Release 2.3-16437

(bottom page menu), Local Connectivity option on top of the page, then select an existing LocalConnectivity and
finally click “View” from the right side menu.

Figure 4.43: Inspect local connectivity on surface.

In order to see actual correlations, one should pick (by mouse click) a vertex on the 3D cortical surface once it
loads in the canvas. The colors displayed nearby, show connected vertices with the selected point.

Annotations Visualizer
This viewer shows ontology annotations linked with TVB connectivity regions. It is composed of two main display areas:

• 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.
Hints:
• There is a 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

4.3.5 Group Display

Discrete PSE Visualizer
Discrete Parameter Space Exploration (PSE) View will show up information on multiple simulation results at
once.
In TVB it is possible to launch multiple simulations by varying up to 2 input parameters (displayed on the X and
Y axis of the current viewer). Each simulation result has afterwards “metrics” computed on the total output. Each
metric is a single number. Two metrics are emphasized in this viewer in the node shapes and node colors.

42 Chapter 4. Web User Interface of TheVirtualBrain

 User Guide, Release 2.3-16437

Figure 4.44: Pick a vertex in 3D and have the corresponding tree node selected on the right.

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

4.3. Simulator 43
User Guide, Release 2.3-16437

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.

Figure 4.46: Preview for Discrete PSE Visualizer, when varying two input parameters of the simulator

A newly incorporated feature is the option to pan the canvas in/out or left/right/up/down. To pan you may click
and drag on top of one of the axes, and to zoom in double click or out shift + double click. This will allow the
inspection of very large batch simulations section by section. The same mouse over, and clicking rules apply from
above.

Figure 4.47: Panning the Graph

The next new tool is the filter button. This allows users to specify threshold values for either the color or size
metric and render results transparent if they are below that value. This tool has the option to invert the threshold
rule which makes the results above that threshold transparent instead. Also, the user has the choice to make their
filter more specific by adding further criteria rows that relate to the one which came before it through selected
logical operators (AND OR). It is worth noting that in order to perform filtering that requires grouping of the
logical operations ([foo and bar] or baz) as different from (foo and [bar or baz]) sequential filters must be applied:
one filter execution then the other.
The last tool to be described in the PSE Discrete Viewer is the Explore tool. This tool is meant to give users the

44 Chapter 4. Web User Interface of TheVirtualBrain

 User Guide, Release 2.3-16437

Figure 4.48: Filter support

(The Explore button is currently disabled because this functionality is not fully implemented)

option to select regions of the Parameter Space to be filled in with new results. Currently only the front end of
this tool is complete, so upon clicking the explore button the mouse cursor becomes a cross hair, and sections of
the graph can be selected. Upon creation of this selection, grid lines are placed to demonstrate where new results
would be added given the user’s chosen step values. To adjust these values simply drag the sliders in the drop
down menu for the explore tool, and the grid lines will adjust until they suit the user.

Figure 4.49: Explore Tool, with Region Selected

Isocline PSE Visualizer

Continuous Parameter Space Exploration View, will show the effect of varying Simulator parameters in a contin-
uous form.
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).
Controls for scaling or zooming the graph are available in this viewer. When you click on the coloured area, an

4.3. Simulator 45
User Guide, Release 2.3-16437

Figure 4.50: Sparse results

Figure 4.51: Preview for Continuous PSE Visualizer, when varying two numeric input parameters of the simulator

46 Chapter 4. Web User Interface of TheVirtualBrain

 User Guide, Release 2.3-16437

overlay window will open, having the 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

Figure 4.52: Preview for Covariance Visualizer

Cross Coherence Visualizer

Displays the cross-coherence matrix. Axes represent brain nodes. The matrix size is number of nodes x number
of nodes.

Figure 4.53: Preview for Cross Coherence Visualizer

4.3. Simulator 47
User Guide, Release 2.3-16437

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 and for every segment. The
thick line represents the Mean and the colored area the SD of CohSpec.

Figure 4.54: Preview for Complex Coherence Visualizer

Cross Correlation Visualizer

Displays the cross-correlation matrix. It is similar to the previous matrix visualizers.

Pearson Coefficients Visualizer

Displays the Pearson cross correlation coefficients matrix. As the correlation matrix is symmetric, only half of it
is actually displayed.

Fourier Spectrum Visualizer

Plots the power spectrum of all nodes in a time-series.
From the top bar, you can choose the scale (logarithmic or linear) and when the resulted Timeseries has multiple
modes and State variables, choose which one to display. After you change a selection in this top bar, the viewer
will automatically refresh.

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).

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.

Wavelet Spectrogram Visualizer

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

48 Chapter 4. Web User Interface of TheVirtualBrain

 User Guide, Release 2.3-16437

Figure 4.55: Preview for Pearson Cross Correlation Visualizer

Figure 4.56: Preview for Fourier Spectrum Visualizer

4.3. Simulator 49
User Guide, Release 2.3-16437

Figure 4.57: Preview for Principal Components Analysis Visualizer

Figure 4.58: Preview for Independent Components Analysis Visualizer

50 Chapter 4. Web User Interface of TheVirtualBrain

 User Guide, Release 2.3-16437

Figure 4.59: Preview for Wavelet Visualizer

Matrix Visualizer
This is a 2D representation of a generic matrix-like result.
In case the current Datatype has more than 2 dimensions, the ND array will be cut, with a default slice. The user
can also input the slice manually.

Figure 4.60: Preview for Matrix Visualizer

Connectivity Edge Bundle Visualizer

Shows structural connectivity coming in and out of a brain region by highlighting paths to other regions.

Pearson Edge Bundle Visualizer

Shows functional connectivity coming in and out of a brain region by highlighting paths to other regions.

4.3. Simulator 51
User Guide, Release 2.3-16437

Figure 4.61: Preview for Connectivity Edge Bundle Visualizer

Figure 4.62: Preview for Pearson Edge Bundle Visualizer

52 Chapter 4. Web User Interface of TheVirtualBrain

 User Guide, Release 2.3-16437

4.4 Analyze
This area offers a set of techniques for data analysis.

Figure 4.63: Current available analyzers

The Analyzers in TheVirtualBrain are not always the best implementations of the algorithms in terms of perfor-
mance, 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 in-
side 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
• 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 nor-
malized 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.

4.4. Analyze 53
User Guide, Release 2.3-16437

The algorithm returns a CrossCorrelation object that contains cross correlation coefficients for all possible combi-
nations 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 cross-
spectral 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.

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 Time-
Series 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.

54 Chapter 4. Web User Interface of TheVirtualBrain

 User Guide, Release 2.3-16437

4.4.6 Temporal covariance of nodes

Compute pairwise temporal covariance of all nodes in a 4D TimeSeries object. Covariance resembles the un-
normalized 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.
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.

4.4. Analyze 55
User Guide, Release 2.3-16437

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.

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 corresponding ICA viewer.

Figure 4.64: Preview for Independent Components Analysis Visualizer

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.

56 Chapter 4. Web User Interface of TheVirtualBrain

 User Guide, Release 2.3-16437

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:
• Degree and Similarity Algorithms
• Centrality Algorithms
• Distance Algorithms
• Modularity Algorithms
• Clustering Algorithms
• Density Algorithms
For more details, please refer to BCT web site

4.4.11 Functional Connectivity Dynamics metric

Analyse functional connectivity dynamics.
The analyser generates:
• The FCD

4.4. Analyze 57
User Guide, Release 2.3-16437

• The FCD segmented, that is the FCD matrix with the entries corresponding to the time points not belonging
to the epochs of stability equal to 1.1. When the epochs of stability are not find, the FCD segmented is not
an output
• The 3 eigenvectors corresponding to the FC of the epochs (if present) or to the global FC. These are Con-
nectivityMeasures which are viewable with the volume visualizer.
The analyser takes as input a time series region, time window length (in ms), spanning between 2 consecutive time
windows (in ms).
The code does the following steps:
1. Calculates the FCD: The entire time series is divided in time window of the fixed length (decided by
the user) and with an overlap decided by the user ( spanning=[time window length] - [overlapping
between consecutive time window]). The data points within each window, centred at time ti, are used
to calculate FC(ti). The element ij of the FCD is calculated as the Pearson correlation between the
upper triangular part of FC(ti) arranged as a vector and the upper triangular part of FC(tj) arranged as
a vector.
2. The FCD is segmented in epochs of stability using the spectral embedding algorithm. We call epoch
of stability a length of time during which an FC configuration stays stable. It is possible to visual-
ize these epochs of stable FC as blocks of elevated inter-FC(t) correlation around the diagonal of the
FCD. We neglect always the first epoch of stability found by the algorithm since should be an artifact
caused by the initial condition of the simulated time series.
3. FCs are calculated over the epochs of stability (excluding the first epoch). When the algorithm does
not find the epochs the global FC is calculated, i.e. the FC calculated over the entire timeseries.
4. The first three eigenvectors of the FCs calculated at step 3 are extracted. We call the “first” eigenvec-
tor the one associated to the largest eigenvalue, the second eigenvector the one associated to the second
largest eigenvalue and so on. Eigenvalues are normalized between 0 and 1.

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

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

58 Chapter 4. Web User Interface of TheVirtualBrain

 User Guide, Release 2.3-16437

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.
• 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 most right side you can go to the next step in configuration: Set Region Scaling.
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

4.5. Stimulus 59
User Guide, Release 2.3-16437

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

Figure 4.67: Preview for Stimulus Surface equations

60 Chapter 4. Web User Interface of TheVirtualBrain

 User Guide, Release 2.3-16437

• 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.
• 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.68: 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.5. Stimulus 61
User Guide, Release 2.3-16437

Figure 4.69: Preview of a spatiotemporal stimulus animation

4.6 Connectivity
In this area you can edit two types of TVB connectivity objects:
• long-range connectivity and,
• local connectivity.
You can also download connectomes from the Allen Mouse Brain Connectivity Atlas.

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

62 Chapter 4. Web User Interface of TheVirtualBrain

 User Guide, Release 2.3-16437

Figure 4.70: Preview for Connectivity Area

Figure 4.71: Large Scale Connectivity configuration page

4.6. Connectivity 63
User Guide, Release 2.3-16437

• a 3D view showing the time evolution of the connectivity matrix

The right column contains the connectivity matrix editor.

Connectivity Matrix Editor

Figure 4.72: 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.

64 Chapter 4. Web User Interface of TheVirtualBrain

 User Guide, Release 2.3-16437

Figure 4.73: Preview for Quadrant Selection

Figure 4.74: Preview for Quick-select list

Figure 4.75: Preview for Select Nodes list

4.6. Connectivity 65
User Guide, Release 2.3-16437

TVB enables you to save a new Connectivity object by clicking on . This entity can be used later on in
TheVirtualBrain Simulator.
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.
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.76: 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).

66 Chapter 4. Web User Interface of TheVirtualBrain

 User Guide, Release 2.3-16437

Figure 4.77: Node selection

Figure 4.78: Node selection

Figure 4.79: Save node selection

4.6. Connectivity 67
User Guide, Release 2.3-16437

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).

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

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.
• 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.81: Set OUT-IN edges to 0

7. Repeat for edges IN-OUT .

68 Chapter 4. Web User Interface of TheVirtualBrain

 User Guide, Release 2.3-16437

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.

Figure 4.82: Select all nodes.

8. Save your new matrix

Figure 4.83: 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.

4.6. Connectivity 69
User Guide, Release 2.3-16437

Figure 4.84: Reload view

Figure 4.85: Preview for Connectivity Viewer 3D Edges

70 Chapter 4. Web User Interface of TheVirtualBrain

 User Guide, Release 2.3-16437

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.

Figure 4.86: 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).

4.6. Connectivity 71
User Guide, Release 2.3-16437

72 Chapter 4. Web User Interface of TheVirtualBrain

 User Guide, Release 2.3-16437

Figure 4.87: Preview for Connectivity 2D Viewer

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.

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

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.

Tip:
If you wish to change:
• the color threshold,

4.6. Connectivity 73
User Guide, Release 2.3-16437

Figure 4.89: 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.

• 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

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 gives 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 corresponds 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.

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.

74 Chapter 4. Web User Interface of TheVirtualBrain

 User Guide, Release 2.3-16437

Figure 4.90: Preview for the space-time display

4.6. Connectivity 75
User Guide, Release 2.3-16437

Figure 4.91: The first slice is the full weights matrix

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

76 Chapter 4. Web User Interface of TheVirtualBrain

 User Guide, Release 2.3-16437

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

4.6. Connectivity 77
User Guide, Release 2.3-16437

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.

Figure 4.94: 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.3 Allen Connectome Downloader

From this page you can initiate an operation which will download data from The Allen Mouse Brain Connectivity
Atlas. See http://connectivity.brain-map.org
This operation needs an internet connection and it will take many minutes to complete. It will produce a Structural
Connectivity in TVB format and a compatible brain Volume object.
Check the Project –> Operations page to see when the import from Allen is done. You can also find your resulted
Connectivity in Project –> Data Structure area.

78 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 API’s 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 visualiz-
ers.

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 notebook’s documentation for more details.

5.3 Terminal shell

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

And in the library profile

79
User Guide, Release 2.3-16437

Figure 5.1: The demo notebooks

Figure 5.2: An open notebook

80 Chapter 5. Console Interfaces of TheVirtualBrain

 User Guide, Release 2.3-16437

$ ./distribution.sh start LIBRARY_PROFILE

Executing distribution.sh
>>>

To work interactively in the Python shell you need a few tvb modules, so typing something like the following will
be useful in this profile:
from tvb.simulator.lab import *

The above line will import all the scientific simulator modules as well as some datatypes that wrap important data
as the Connectivity matrix and cortical Surface. Afterwards, you can use the terminal as a regular python shell.
The script (distribution) is located in the bin folder and it has 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.3. Terminal shell 81

User Guide, Release 2.3-16437

82 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
minimal 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 subject’s head (eg, structural MRI AND DTI Data)
Structural Dataset
(a collection of T1/T2 weighted MRI scans + 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, a complete structural dataset also contains head model
surfaces, information about the units (areas, lengths, connectivity strengths), information 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)
In general, all the steps in the processing pipeline should be documented, so it’s possible to apply the same
treatment to subsequent datasets. Sending pieces of information to different files without descriptions from where

83
User Guide, Release 2.3-16437

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 it’s not reproducible). We can’t provide any meaningful help to integrate/check or validate
incomplete datasets.
Ideally, any volumetric data (e.g., in NIFTI format), surface data (e.g., GIFTI format) or combination thereof
(e.g., 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 (i.e., 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) points 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
community. 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 software 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
functionality.

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 doesn’t 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 correspondence between integer values in the parcellation mask and anatomi-
cal/human readable labels should be provided if they are not specified in the volume file.
Are region labels essential?
From view point of the implementation of The Virtual Brain the labels are essential.

84 Chapter 6. A Description of a Complete Dataset

 User Guide, Release 2.3-16437

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 (e.g., 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 don’t 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 masks being used in the community. NOTE: REF par-
cellation papers. One of the main problems is that parcellation masks are often custom made and
subsequently modified, so it becomes very difficult to track the origins. To begin with, we suggest to
use parcellation masks provided by neuroimaging software tools like FSL AAL 90. If you want to
use a custom made parcellation mask, 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 stan-
dard space such as MNI. These coordinate systems should be consistent with the surface’s coordinate
systems.

6.3 Connectivity and path length data

What is required for building 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.4 Cortical Mesh

We encourage to use the MNI brain template (eg, MNI152) to register your subjects data and extract the corre-
sponding cortical surface.

6.3. Connectivity and path length data 85

User Guide, Release 2.3-16437

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. Mod-
eling 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 Za-
lesky), 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. It’s 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 triangle 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 ‘nor-
mals’. 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

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. We are talking about a one to many relationship
for the vertices of the cortical surface and one to one relationship for the remaining non-cortical
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?
It is obtained by combining the lh.aparc.annot and rh.aparc.annot files that FreeSurfer generates for a
particular subject. The details of the resulted Region Mapping depend on the preprocessing pipeline
used, some of them cut out the regions that do not have any vertices assigned, others keep them etc.

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.
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)

86 Chapter 6. A Description of a Complete Dataset

 User Guide, Release 2.3-16437

The surfaces describing a subject’s head: skin, skull, cortical surface. See the description below.
A Minimal Structural Dataset For TVB:
All 3D coordinates should be consistent, i.e., vertices, parcellation masks, 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, i.e. coor-
dinates, 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.
– 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 complete dataset (connectome, surface, sensors, gain matrix for eeg, etc...).

Note: Check the DataExchange chapter of the User Guide manual.

6.6. Head model 87

User Guide, Release 2.3-16437

6.7 The TVB demonstration dataset

Note: 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 it shouldn’t be used/relied-upon for that purpose. References,
where appropriate, are given. Also, this is an open source project and contributions are greatly appre-
ciated. 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 weren’t 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 aren’t 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. thala-
mus 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
• PCip: Cortex of the intraparietal sulcus
• PCm: Medial parietal cortex (Precuneus)
• PCs: Superior parietal cortex
• PFCcl: Centrolateral prefrontal cortex

88 Chapter 6. A Description of a Complete Dataset

 User Guide, Release 2.3-16437

• 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 dataset to serve as a default dataset available to users
who can’t or aren’t 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 interested in contributing to a dataset, please contact the tvb google group.
• Algorithm for calculating the region mapping, given a coregistered Cortex and Parcellation Mask,
including an “island” removal/correction mechanism to deal with the imperfect alignment that will ex-
ist, even with coregistered data, between an individual’s cortical surface and the “generic” parcellation
mask.

Note: Demo data as described in this chapter, can be found on Zen-

odo: https://zenodo.org/record/4263723#.YL9x4jaA7t0, or inside TVB_Distribution,
under the following path: TVB_Distribution/tvb_data/Lib/site-packages/tvb_data/ on
Windows, TVB_Distribution/tvb_data/lib/python3.x/site-packages/tvb_data/ on Linux, or
TVB_Distribution/tvb.app/Contents/Resources/lib/python3.x/tvb_data/ on Mac. These demo
files can be used together with the GUI and/or the script interfaces, or taken as reference for
you, when creating TVB compatible dataset.

6.8 Other datasets

6.8.1 Hagmann
What has been provided/shown :

6.8. Other datasets 89

User Guide, Release 2.3-16437

• A 998 ROIs connectome (weights + resampled distances)

• A mapping to the parcellated connectome of 66 regions
• Label and anatomical names
• Info about the coordinate system: Talaraich
What’s 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, it contains 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.
What’s missing:
• Preprocessed diffusion data (e.g., 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/

90 Chapter 6. A Description of a Complete Dataset

 User Guide, Release 2.3-16437

• MRtrix: https://www.mrtrix.org/
• 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 91

User Guide, Release 2.3-16437

92 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 com-
munity. 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. H5, 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.
TheVirtualBrain‘s 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 TheVirtu-
alBrain stores its data. Basically there are two major storage areas:
1. Database - where general information/metadata and relations between stored elements are stored (e.g. as-
signment 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, we have a folder containing
a 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 a GUID, which makes it unique on
every system where that data exists.

93
User Guide, Release 2.3-16437

7.1 Exchange Projects

TheVirtualBrain product can be installed both on a server, to be used concurrently 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 a view model H5/HDF5 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 can be done in two ways: with or without links.
Export in TVB Format (without links) 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.
Export in TVB Format with links will export not only the chosen file, but all other files which are linked to
this datatype as well (for example, if you export a region mapping, it will also export the linked connectivity and
cortical surface). This second type of export will result in a ZIP file, which contains an HDF5/H5 file for each
exported datatype.
In case you want to process HDF5 files with Matlab you can find API documentation here:

94 Chapter 7. TheVirtualBrain Data Formats

 User Guide, Release 2.3-16437

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 a single HDF5 file.
2. if a data type group is exported, the result is a ZIP file containing:
• a list of folders for each operation
• each operation folder containing 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.
#. if a simple data type is exported with links, the result is a ZIP file containing a HDF5 file for the exported
datatype and a HDF5 file for each linked datatype.

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 defined and can be changed in the Application Settings area, depending on the configura-
tion/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 has to decide if it represents a datatype with links or a datatype group.
More specifically, if it finds folders inside the zip file, it will know it is a DatatypeGroup import, otherwise
it is an import with links.
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
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. Import Data 95

User Guide, Release 2.3-16437

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, TheVirtual-
Brain 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 importing a connectivity from a ZIP file. The ZIP file should contain files with connectivity
details as follows:

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

96 Chapter 7. TheVirtualBrain Data Formats

 User Guide, Release 2.3-16437

• 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 the 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 a 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 a 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 orientations (3 float values separated with
spaces or tabs)
5. If any file name contains “area” it will be considered as a 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 a 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 a 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 97

User Guide, Release 2.3-16437

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
The uploaded ZIP file should contain files with a specified naming schema and format as follows:
1. If any file name contains “vertices” it will be considered as a 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 a 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 a 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. 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 the 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.

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.

98 Chapter 7. TheVirtualBrain Data Formats

 User Guide, Release 2.3-16437

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 an uploaded .gii file contains a surface (Cortical Surface or SkinAir) during import, then TheVirtualBrain stores
the found vertices / triangles and computes normals for them.
In case a .gii file contains a TimeSeries, the user will be asked to specify what is the surface for which the
TimeSeries is imported. Important to know: the number of vertices from imported time series must be the same
as the one selected for the surface. Otherwise the 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 handle
cases when metadata is defines in .gii (XML) file and real data in external files.

7.3.8 Import Region Mapping

A Region Mapping in TheVirtualBrain is a vector, defining a mapping between a Cortical Surface and a Connec-
tivity. At import time, you will need to have at least 2 entities in the TheVirtualBrain system: a Connectivity and
a 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.9 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.

7.3. Import Data 99

User Guide, Release 2.3-16437

100 Chapter 7. TheVirtualBrain Data Formats

 CHAPTER

EIGHT

COPYRIGHT NOTICE

Note: TheVirtualBrain is a brain-simulation software. See also http://www.thevirtualbrain.org

© 2012-2022, Baycrest Centre for Geriatric Care (“Baycrest”) and others
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public
License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any
later version.
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 for more details.

8.1 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)

101