Scripting

cvu is highly scriptable. cvu has two types of scripting modes, interactive scripting and automated scripting. In interactive scripting, the user interactively types into the in-program shell. In automated scripting, the user prepares a series of commands for cvu to run as soon as it finishes loading, which are then executed. For examples of automated scripts, see the examples at the bottom of this page.

In both scripting modes, scripts execute in the context of the CVUGui object, which is a HasTraits that comprises the main programs View object. You can access the program internals -- all runtime attributes -- using scripting. For instance, print self returns a object, and executing self.controller.ds_orig.dv_3d.vectors.module_manager.scalar_lut_manager.lut_mode='autumn' changes the color scheme of the connections shown.

You can use automated scripting in either of two ways. You can execute automated scripting interactively, by typing script('path/to/script.txt') in the shell. Or, you can pass the script as a command line argument cvu --script /path/to/script.txt

Keep in mind that in the scripting environment, the default working directory is /path/to/cvu/cvu (which allows SUBJECTS_DIR to sometimes be listed as .).

Also keep in mind that there is no security in scripting mode. In pythonic style, scripts are allowed to mess with any part of the program internals. You could also write a script that uses os.system or subprocess.Popen to run any other arbitrary program. Additionally, incorrectly written scripts will typically just fail and print out their error messages to the 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.

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]