Note

This manual is still under development and there could be some incomplete parts, marked as ‘Work in progress’.

ViSimpl Introduction

After decades of independent morphological and functional brain research, a key point in neuroscience nowadays is to understand the combined relationships between the structure of the brain and its components and their dynamics on multiple scales, ranging from circuits of neurons at micro or mesoscale to brain regions at macroscale. With such a goal in mind there is a vast amount of research focusing on modeling and simulating activity within neuronal structures, and these simulations generate large and complex datasets which have to be analyzed in order to gain the desired insight.

In such context we present ViSimpl, which integrates a set of visualization and interaction tools that provide a semantic view of brain data with the aim of improving its analysis procedures. ViSimpl provides 3D particle–based rendering that allows visualizing simulation data with their associated spatial and temporal information, enhancing the knowledge extraction process. It also provides abstract representations of the time–varying magnitudes supporting different data aggregation and disaggregation operations and giving also focus and context clues. In addition, ViSimpl tools provide synchronized playback control of the simulation being analyzed. Finally, ViSimpl allows performing selection and filtering operations in association with NeuroScheme application. All these views are loosely coupled and can be used independently, but they can also work together, both in centralized and distributed computing environments, as linked views enhancing the data exploration and analysis procedures.

This documentation is for ViSimpl version 1.8.10 that can be obtained from the homepage.

Hardware requirements

ViSimpl application requires a graphic card that supports OpenGL 3.3 at least. It is also recommended (depending on dataset size) to use a multi-core CPU for parallel processing deployment. The size of the datasets that ViSimpl is able to load depends on the available memory on the machine.

SimPart and StackViz synchronization

ViSimpl is composed of two applications: SimPart for 3D visualization (spatial data) and StackViz for time data manipulation (temporal data). For SimPart and StackViz to synchronize events a ZeroEQ discovery provider must be installed in the machine. ZeroEQ applications are linked using automatic discovery based on ZeroConf protocol or through explicit connection addressing using hostname and port because of that a service like Avahi on Linux or dnssd on Mac/Windows (like Bonjour) must be installed. If that service is not present SimPart and StackViz will still be usable but won’t be able to synchronize. SimPart includes a version of StackViz so the functionalities present in StackViz are available in SimPart without the requirements of ZeroEQ.

Installation and running

ViSimpl can be downloaded from the ViSimpl Homepage for Linux and Mac operating systems and executed locally. Additionally it can be executed using a docker image.

Docker containers

The docker containers for ViSimpl can be found on Docker Hub. It’s recommended to use the highest tag number (latest official release) or the git master (represents the latest commit to master branch, and usually are the same as the highest tag number).

Executing locally

The SimPart and StackViz application options and parameters are:

OPTION PARAMETER DESCRIPTION
--version none Shows the version of the application.
--help none Shows the options and arguments used for executing the application.
--testFile destination_path Generates a test file dataset and saves it in the specified destination path. If the destination path is not specified the test files will be saved in the same directory as the application executable (if possible). Only available in SimPart
-bc path_to_bc_file Load BlueConfig file.
-target target_label Specifies target label of the BlueConfig file.
-csv

path_to_network_file

path_to_activity_file

 Load CSV dataset files. Both the network and the activity files must be present.
-rest url port Load data from the given url and port using NEST Rest API.
-se path_to_events_file Load events file.
-scale X,Y,Z Sets the 3D view scale in X,Y and Z axis.
-zeq zeroeq_id Opens a ZeroEQ channel with the specified id.

-ws

--window-size

 width height Specifies the size of the application window.

-fs

--fullscreen

 none Sets the application window to fullscreen mode.

-mw

--maximize-window

 none Maximizes the application window to the desktop resolution.

If the options are incompatible or its parameters invalid the application will abort the execution and will show the help message in the console.

Test dataset

A test data for SimPart and StackViz can be generated by executing:

./visimpl --testFile

SimPart will start loading the test data automatically. If the application can’t write the test files it will abort the execution and inform of the error, in that case a path must be specified where the user has permissions to write.

./visimpl --testFile destination_path

Docker examples

Executing both applications from docker:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
xhost +local:docker
# Pull the image.
docker pull vglab/visimpl:1.8.10-nvidia-ubuntu-16.04
# Download example data
mkdir data
cd data
# Download a test dataset or move test files to data directory.
cd ..
# Run example
docker run --gpus 1 -ti --rm -e DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix -v /etc/machine-id:/etc/machine-id -v $(pwd)/data:/data --privileged vglab/visimpl:1.8.10-nvidia-ubuntu-16.04 /usr/bin/visimpl.sh

To execute SimPart only the user must use the /usr/bin/simpart.sh call, and to execute StackViz follow the same steps but use /usr/bin/stackviz.sh in the docker call. All scripts supports the parameters specified in the previous table with the exception of –testFile parameter as is only available in SimPart.

To test the applications in a docker enviroment:

1
2
3
4
5
6
7
8
9
xhost +local:docker
# Pull the image.
docker pull vglab/visimpl:1.8.10-nvidia-ubuntu-16.04
# Run bash inside docker
docker run --gpus 1 -ti --rm -e DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix -v /etc/machine-id:/etc/machine-id -v $(pwd)/data:/data --privileged vglab/visimpl:1.8.10-nvidia-ubuntu-16.04 bash
# Executing inside the container
simpart.sh --testFile &
# With the test file generated and loaded in SimPart, execute StackViz with the dataset.
stackviz.sh -csv /usr/bin/network.csv /usr/bin/activity.csv