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:

cvu.load_parc(parcellation, ordering, new_dataset=False, dataset_name=None, dataset=None, subjects_dir='.', subject='fsavg5', surface_type='pial')¶

Loads a parcellation, either onto a dataset or creating a new dataset. This function is a scripting helper. In other words, instead of clicking on the GUI or simulating button presses, this function is provided for scripting purposes to just simulate the process of loading a parcellation.

Parameters :

parcellation : str The parcellation name. For instance, if your parcellation’s annotation files are called lh.aparc.annot, the parcellation name is ‘aparc’. Similarly if the annotation file is called lh.aparc.gii, enter ‘aparc’. ordering : str | list(str) The name of a text file containing the parcellation ordering. Alternately, a list of label names. new_dataset : bool If True, spawns a new dataset instead of placing the parcellation on an existing dataset. Default value is False. dataset_name : str | None Required if and only if new_dataset is True. If new_dataset is True, specifies the name of the new dataset. Otherwise, has no effect. dataset : instance(cvu.dataset.Dataset) | None Required if and only if new_dataset is False. If new_dataset is False, specifies the dataset onto which to load this parcellation. If new_dataset is True, has no effect. subjects_dir : str The superordinate directory used to load the annotation, surface, and segmentation files at $SUBJECTS_DIR/$SUBJECT/{surf|label|mri}/* . The default value is ‘.’, the current working directory. Under normal circumstances this is the working directory relative to cvu’s main.py file, which is /path/to/cvu/cvu. subject : str The subject name used to load the annotation, surface, and segmentation files at $SUBJECTS_DIR/$SUBJECT/{surf|label|mri}/* The default value is ‘fsavg5’. Some files for fsavg5 are provided in the cvu installation. surface_type : The surface to load. The default value is ‘pial’.

Returns :

dataset : instance(cvu.dataset.Dataset) The instance of the dataset now holding this parcellation. Helpful if new_dataset is True.

cvu.load_adj(matrix, dataset, ordering=None, ignore_deletes=False, max_edges=0, field_name=None, required_rois=[], suppress_extra_rois=False)¶

Loads a matrix. This function is a scripting helper. In other words, instead of clicking on the GUI or simulating button presses, this function is provided for scripting purposes to just simulate the process of loading a matrix into a dataset.

Parameters :

matrix : str | instance(np.ndarray) Filename of an adjacency matrix in a supported format (numpy, matlab, or plaintext). Can also be a numpy matrix. dataset : instance(cvu.dataset.Dataset) The dataset into which to place this adjacency matrix ordering : None | str | list(str) Filename of an ordering file describing the matrix order. Default value is None. If None, matrix is assumed to be in parcellation order. Can just be a list of label names. ignore_deletes : bool If True, ‘delete’ entries in the ordering file are ignored. Default value is False. max_edges : int Default 0. Leave as default or see wiki documentation. field_name : None | str Needed to tell the field name of a matlab matrix. Required for matlab matrices, otherwise ignored required_rois : list(str) A list of ROIs whose labels must be shown in the circle plot. The default value is the empty list, signifying no restrictions. suppress_extra_rois : bool If true, only the ROIs in required_rois are shown on the circle plot.

Examples of automated scripts

see Scripting Examples