-
Notifications
You must be signed in to change notification settings - Fork 14
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 eval
ing 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.)
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]
.
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
anddv_3d.syrf_rh
are Mayavi surface objects representing brain surfaces created withmlab.triangular_mesh
-
dv_3d.nodes_lh
anddv_3d.nodes_rh
are Mayavi glyph objects representing ROI nodes created withmlab.points3d
-
dv_3d.vectors
is a Mayavi vectors object representing the connections, created withmlab.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.
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.
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.