Getting Started

cvu is meant to be run as a standalone application, although some support for scripting exists (that is something I need to work on over the next months).

To run cvu, execute
path/to/cvu/run

It is also possible to specify command line arguments to load data directly from the command line, but usually easier to just run with no arguments and load data from the GUI.

If all of your dependencies resolve, the interface will open showing some sample data:

This data is one epoch of synchronization likelihood connectivity of MEG data from a single subject filtered to the alpha band.

Feel free to click around at this point, but probably you are more interested in visualizing your own data.

Network visualizations in cvu require two things: a parcellation and an adjacency matrix.

• A parcellation is an annotation file that comprises a collection of labels that provide geometric information about the location of ROIs on the cortical surface.
• An adjacency matrix is a matrix describing a network. The rows and columns of the matrix correspond to ROIs, and the entries of the matrix correspond to weighted connections. In cvu matrices must be symmetric.

In addition, you need one piece of information in order to bridge together the parcellation and the matrix, an ordering file.

• An ordering file is a text file whose entries correspond to region names. These region names are stored in the parcellation file, but not in the matrix file. Basically, the ordering file tells the parcellation what order the ROIs (the rows and columns of the matrix) refer to.

An ordering file looks something like this

lh_parstriangularis
lh_superiorfrontal
delete
lh_anteriorcingulate\n
...

The delete keyword has a special meaning, which we will see later.

To load your data, you'll have to first load the parcellation and then the adjacency matrix.

First, click on "load a parcellation". You'll see this window:

For now, leave all of the fields that are filled in as they are. Next to the parcellation field, type laus125. For "label display order", click the button and navigate to /path_to_cvu/orders/laus125_alph.txt

You should see this:

What has happened is that we loaded a parcellation called laus125. This parcellation is represented by two annotation files in path_to_cvu/cvu/fsavg5/label called lh.laus125.annot and rh.laus125.annot. These files are in freesurfer annotation format. If your data does not use one of the Lausanne parcellation schemes (see Cammoun et al. 2012), then you will have to create a file like that. You can do it using freesurfer's mris_label2annot if you have label files for your ROIs. You should store the annotations in the label subject's freesurfer reconstruction, and you'll just need to set the SUBJECTS_DIR and SUBJECT fields accordingly when you load the parcellation. Specifically, cvu will look for the annotation files in $SUBJECTS_DIR/$SUBJECT/label.

The sample visualizations we've seen so far use the fsaverage5 average brain. This is ok, even if our subject is not as symmetrical as fsaverage5, because we are looking for the complex properties of networks. However, if you specify your subject in place of 'fsavg5', you can look at your subject's morphology too.

Now, let's load a matrix. Click on the load matrix dialog. It looks like this:

For now, just load the sample matrix provided at path_to_cvu/cvu/data/sample_laus125.npy. Click on the "matrix" field and navigate to this file, or your own matrix file. Leave all of the other fields blank. It should look like this:

The box labeled "field name" is only relevant to matlab (.mat) matrices. If you have a .mat file, you'll also need to specify the variable name of the adjacency matrix within the matrix file here.

The "label order" field is for an ordering file. Remember that ordering files are text files with ROI names in them. You already gave cvu an ordering file earlier when you specified the file at path_to_cvu/orders/laus125_alph.txt, which has the entries of the Lausanne parcellation in alphabetical order. Why would you specify one again? Well, you don't have to, but you can. You can do this if you want to display the entries of the ordering file in a different order than the order in which they actually exist in the matrix. The ordering file you specified with the parcellation controls the visualization order. The ordering file specified with a matrix tells cvu, "This matrix is not in visualization order. It is in this order. Put it in visualization order. Except for any entries marked as delete; skip those entries." If you don't specify any ordering file with the matrix, cvu just assumes it is in visualization order.

The reason this functionality exists is for usability. It can be convenient to create an adjacency matrix with entries in alphabetical order. However, you probably don't want to visualize your data in this order. Try it out: reload the parcellation and give it the visualization order path_to_cvu/orders/laus125_cmp.txt. Then, load the matrix again with the order path_to_cvu/orders/laus125_alph.txt.

If you followed my instructions, then the program just gave you the following error!

Why did it do this? The reason is because of the delete entries in the ordering file. laus125_alph.txt has some delete entries in it, because the parcellation contains nodes for unknown and corpus_callosum that are not widely of great interest (though corpus_callosum can be of interest in tractography data). When we specified the ordering file to load along with the adjacency matrix, it faithfully deleted the elements that we asked it to delete, but those elements corresponded to real nodes in the parcellation. (This is always true. Entries labeled delete have no effect when specified in the visualization order. They are only meaningful when loading matrices, or scalar quantities. You should use them only if the matrix has unwanted ROIs in it, such as unknown in freesurfer's aparc).

In order to get the right behavior in this case, we should tell cvu to ignore the delete entries by ticking the ignore deletes button. Now, it produces the correct visualization. The 3D brain visualization shouldn't have changed, but compare the patterns observed in the matrix and circle visualizations to the figure shown above on this page. Order matters!

This tutorial was designed to teach you how to load parcellations and matrices within the program. However, getting your data to actually show up usefully in cvu might be more tricky, because it requires you to have set up a parcellation and matrix. See Strategies for parcellating and matrix creation.