Scripting

Open a cvu instance and type in the command:

self.controller.ds_orig.opts.activation_map.cmap='autumn'

You've just changed the color scheme of the connections shown on the glass brain. This is the essence of scripting in cvu -- using the power of code to do things for you quickly, without navigating through menus.

In addition to doing interactive scripting inside the program shell, you can additionally write scripts beforehand to set up an interactive scene and/or produce figures in batch. To do this, you can invoke CVU with the --script command line argument, as in ./run --script path/to/script.txt. You can also call the script directly in CVU's python shell, by typing script('path/to/script.txt').

(Note that both modes of batch scripting execute scripts by evaling the contents of the file they are provided with path/to/cvu/cvu as the default working directory. This means that scripts will always run in the context of the CVUGui object and have access to program internals. Consequently, it also means that the scripting features can do anything a python process can do and offer no security whatsoever. Incorrectly written scripts will typically dump their errors to console.)

Design

The GUI is comprised primarily of several viewports and a controller. The viewports show the three different views -- 3D Brain, Matrix, and Circle views -- of the network. Each viewport is connected to a dataview that is attached to the dataset. These dataviews are called dv_3d, dv_mat, and dv_circ, respectively, for the 3D Brain, Matrix, and Circle views.

The controller, which is called controller manages multiple datasets. A dataset is a data structure that holds a brain network and all of its resident attributes, such as the adjacency matrix, dataviews, and network statistics. There is only one controller, and all of the datasets shown in the program are contained inside of it.

CVU can show any number of datasets on the screen at a time. One dataset -- is shown in the main GUI window from the time the program starts. Other datasets can be created by loading new data, which will be shown in different windows.

To access a dataset you must go through the controller. To access the dataset on the main GUI window, you can use self.controller.ds_orig. To access any other dataset, you must know the name of the dataset (which is specified at data creation and can be changed in the controller), and you will access it as self.controller.ds_instances[name].

Some important attributes of dataviews

Many of the interesting things you can do with scripting involve adjusting the actual parameters of the underlying visualizations, especially in the 3D mayavi scene. Here is a brief description of the attributes (which can all be edited directly) of what goes on in the Dataview objects:

• dv_3d.syrf_lh and dv_3d.syrf_rh are Mayavi surface objects representing brain surfaces created with mlab.triangular_mesh

• dv_3d.nodes_lh and dv_3d.nodes_rh are Mayavi glyph objects representing ROI nodes created with mlab.points3d

• dv_3d.vectors is a Mayavi vectors object representing the connections, created with mlab.vector_scatter -> mlab.pipeline.threshold -> mlab.pipeline.vectors

• dv_circ.circ is a matplotlib/pylab figure

• dv_circ.circ_data is a list of matplotlib Patches. The first min(n*(n-1)/2, max_edges) patches represent connections, while the last n patches represent the nodes of the network.

Scripting helpers

There are two helper functions in the global namespace designed to facilitate scripting:

• load_parc -- Loads a parcellation, providing the same functionality as if you clicked the load parcellation button. Takes the parcellation name, ordering file, and subject morphology (which defaults to fsaverage5) as arguments. Instead of providing a file, the ordering can be provided as a list of python strings. Can optionally create a new dataset which is shown in a new window, or use an existing window (i.e., reuse an existing dataset) instead.

• load_adj -- Loads an adjacency matrix, taking the dataset and optionally an ordering as arguments. The matrix can optionally be specified as a well-formed numpy matrix instead of a matrix file and the ordering can optionally be specified as a list of python strings.

See the docstrings for these functions.

Examples of automated scripts

The integration tests included in the development version of cvu make use of the automated scripting mode. Many of these tests simulate many menu interactions in order to test the GUIs -- that is, directly inserting information into the GUI and asking the GUI events like button presses. However, it is usually possible to bypass the menu interactions and make calls to the controller and the datasets directly (it should almost never be necessary to access the viewports that those datasets use from the controller).

Most of the following examples come from the integration tests. However, both a menu-intensive and non-menu-intensive version of each script is shown.

[put examples here]