User Tutorial [neuro] - Cortical Thickness Panel

Updated for release version: 1.0.20-alpha

Introduction

The Cortical Thickness Panel is intended to provide an interface for scientists to visualize, organize, query, Q/C, and manipulate the output of a cortical thickness pipeline. The panel was originally designed to handle data from the CIVET pipeline, but is equally useful for output from the Freesurfer pipeline. Assuming you have already computed results using one of these pipelines, this tutorial will take you through the process of setting up the panel to point to your pipeline output, setting up windows, and visualizing the data for a selected subject. It will also run through the process of creating and setting up a data source for performing quality control on your data.

Setting up a project

The first thing we need to do is to point the panel at your data. To do this, select "Cortical Thickness Panel" from the combo panel, and expand the "Project" category. Click "Edit", and the following dialog box will appear:

cortical_thickness_dialog_both.png

I/O

The I/O tab allows you to set up the loaders required to load your data. First, specify your CIVET output directory by clicking "Browse.." besides the "Subject dir" text box. Navigate to the folder containing your CIVET output, which will contain a set of subdirectories — one for each of your subjects. Next, type your subject prefix, which you would have specified when running the CIVET pipeline. If you are unsure of this, open a file browser and go to the "thickness" folder of one of your subjects. They will contain files of the form:

nki_0102157_native_rms_rsl_tlink_30mm_left.txt

Your subject prefix here is "nki_" (importantly, don't forget to include the underscore). The subject ID is "0102157".

Next, specify the relevant file loaders. Here, you want all your loaders to be "Minc" loaders, as shown. The writers are (in the present version) unused, so you can safely ignore them. Everything else can be left as it is.

Volume

The Volume tab lets you specify the parameters for loading volumes. This includes the colour map, whether the volume has alpha (transparency), and how to set the colour limits.

Under "Intensity", you can choose your colour map first. Greyscale is a typical way to view anatomical volumes, but for the purpose of determining grey matter / white matter contrast, it's nicer to have some colour. I chose the "nederland" colour map (so called because it is comprised of red, white, and blue). You can play with this later on if you want.

The "Set alpha" check box determines whether the volume will be rendered using transparency. If true, all values below a colour map's minimum will be transparent. Also, colour maps which specify transparency (alpha) will only do so if "Set alpha" is true. This is especially useful if you want to render in 3D, or with multiple volumes in 2D. For the present tutorial, we won't be doing either of these, so let's set the value to false.

"Data type" tells the loader to use a specific data type for the volume. If false, the type of the source volume is used. This isn't always ideal, however; here you'll generally want to check the box and select "Float" as the data type.

The next six lines determine the default colour mapping when a subject's volume data are loaded. "Fixed intensities" specifies a fixed colour mapping window in terms of brightness (window middle) and contrast (window width). "Relative intensities" uses the volume's histogram to determine the window. Since subject volumes are typically varied in their brightness, the latter option is usually best. Select "Relative intensities" and change the High Percentile to 97.

"Volumes as composite" is only relevant if you are loading multiple volumes of the same size. We won't be doing this today, so uncheck this box.

We're ready to go, so click OK.

Next, to populate the list of subjects from your project directory, click the "Apply" button. My list looks like this:

cortical_thickness_subject_list.png

Setting up windows

Before we go any further, we want to set up a few windows to view our data. For this tutorial, we want five windows:

  1. A 3D window: for rendering the CIVET surfaces
  2. Three 2D windows: for rendering horizontal, coronal, and sagittal sections showing where the surfaces intersect the volumes
  3. A Data Source window: for QC results

To do this:

  1. Right-click the empty screen > Add Window > Graphic3D > "Graphic 3D"
  2. Right-click the "Graphic3D" window > Split horizontal > Graphic2D > "Horizontal"
  3. Right-click the "Horizontal" window > Split horizontal > Data Table > "QC"
  4. Right-click the "Graphic3D" window > Split vertical > Graphic2D > "Sagittal"
  5. Right-click the "Horizontal" window > Split vertical > Graphic2D > "Coronal"

Next we want to set sources for these windows. For the Graphic 3D window, this is simple enough:

  • Right-click the "Graphic3D" window > Set source > "Default model"

For the 2D windows, we need to have section sets defined. Luckily, the ones we want have already been provided with ModelGUI; you just have to load them. Open the "File Panel", and select "Mgui Shape Models (*.smod, *.smod.gz, *.xml)" as the input file type. Click "Browse.." and navigate to your ModelGUI installation folder. You'll find a file named "sections.smod.gz" in the "data" folder. Select this and click "Read Data". To set the window sources:

  1. Right-click the "Horizontal" window > Set source > "Default model.horizontal"
  2. Right-click the "Coronal" window > Set source > "Default model.coronal"
  3. Right-click the "Sagittal" window > Set source > "Default model.sagittal"

We can put off the QC window for the time being. Now, your window should look like this:

cortical_thickness_setup_windows.png

Selecting shapes

Back in the Cortical Thickness Panel, select the first of your subjects and click "Preview selected". The Shapes section will fill up with lists of all the loadable files in each subject directory. For our Q/C, we want to select (Ctrl+click) four surfaces:

  1. surfaces/gray_surface_left_81920.obj
  2. surfaces/gray_surface_right_81920.obj
  3. surfaces/white_surface_left_calibrated_81920.obj
  4. surfaces/white_surface_right_calibrated_81920.obj

..and one volume:

  1. final.t1/final.mnc

(Note: loading of vertex-wise surface data — e.g., thickness — is not yet implemented for the cortical thickness panel).

Once you've selected these, we're ready to go. Click "Load selected subject" and the data for the first subject (selected above) will be loaded. A progress bar will appear at the bottom of the screen, and the surfaces and volumes will be rendered in the graphic windows.

The initial views are not ideal. To fix the 3D window, use the mouse wheel, or Ctrl-Left-Drag, to zoom out. You'll see a blue square, (or the top of a head, if you left "Set alpha" selected earlier). To center the data in the 2D windows, right click on each window and select "Zoom extents". The window should now look like:

cortical_thickness_load_subject.png

We want to see a 3D surface instead of a blue square — to do this, use the Tree Panel and expand Shape Models > Default Model > Cortical Thickness Set > t1_final_mnc > Attributes. This will allow you change the attributes of the Volume3D object. Uncheck the box beside 3D.Show, and the box in the 3D window will disappear, revealing the cortical surfaces.

Customizing shape attributes

Before we start our QC, we want to do a little tweaking of the visualization.

Surface mesh colours

The 2D surfaces are rendering as grey lines, which aren't particularly bold on top of the volume slices. By default, 2D shapes "inherit" their attributes from their parent 3D shapes — in this case, the 3D surfaces. This can be changed by unchecking the "InheritFromParent" attributes of these objects. Doing this for the white surfaces first, you will now have dark blue lines, which are sufficiently bold. For the grey surfaces, you can additionally change the line colour to a dark red, by clicking the box beside the "2D.LineColour" attribute.

Our 3D surfaces are still grey. This is not particularly useful if, for instance, we want to look for places where they cross one another. We can make the white (inner) surfaces a bright red by changing their "3D.FillColour" attributes. After all these changes the screen should look like this:

cortical_thickness_set_attributes.png

Volume colour map

You might also not be happy with the volume's colour map; the histogram-based relative intensity limits don't always find the best contrast. To play with this, open the "Volume Panel", and select "Default Model.t1_final_mnc" as the shape. Expand the Intensity and Histogram sections, and you should see something like:

cortical_thickness_volume_panel.png

Use the "Slice" slider bar to scan through the volume's horizontal slices.

You have many options to define the volume's colour mapping. You can use the sliders at the top of the Intensity section, type exact values in the Min and Max boxes, drag on the image itself (left drag = contrast, right drag = brightness), or you can use the three control points on the histogram (circle = brightness, squares = upper and lower limits). My favourite approach is the histogram controls, which give the finest control over the map window. You can also change the colour map itself, and specify whether it has transparency (alpha).

When you are happy with the colour mapping, click Apply in the Intensity section. The graphic windows will show the change.

See the Volume Panel page for more detail on the options.

Perusing the data

Now you are ready to have a look at this subject's data. The 3D window can be spun around (right-drag), to search for crossing surfaces or abnormal morphology that warrants closer inspection. A particularly troublesome area is the superior parietal. When you find a point of interest, you can right click on it and select "Move sections to vertex", which will move all 2D windows to the selected vertex. You can then examine the suspect morphology from three different orientations. Note, you can also move sections to a 2D point by right-clicking on a 2D section window and selecting "Move sections here".

cortical_thickness_move_to_vertex.png

Browsing subjects

Once you're done with a subject, you can load the next subject's data from the Cortical Thickness Panel, simply by clicking "Next >". This will iterate the selected subject in the above list, and load and display the data. If you have a specific subject in mind, you can select him from the list yourself and click "Load selected subject". Using these controls, you can browse through all your subjects, performing QC (or some other analysis) on each in turn.

Quality control with a data table

The final thing you may want to do is set up a database to store your QC results (or other observations). We can do this using the Data Sources interfaces. Note that you will have to have already set up a database server, such as PostgreSQL or MySQL, to do this (these are not installed by default). For more on this, see this tutorial.

Create new data source

Assuming we have a data source driver defined and working, we can create a new table for our QC. From the Datasource Panel, expand Sources, select "<-NEW SOURCE->", and click "Define". In the dialog box, check the "New" box, and fill in the text boxes with your user name, password, and a name for the new data source:

cortical_thickness_new_db_dialog.png

Click OK and you should see a success message, which means the server has successfully created a new table. If not, something is wrong with the data connection (bad password?), or perhaps you used an invalid name. Check the terminal console for an error message. Otherwise, click "Create" to create the data source object in ModelGUI, and then "Connect" to connect to it.

Create new table

Here, we want to create a table with columns for our subject ID and relevant QC information. We can do this in one of two ways:

  1. Using the Tables > Add New button
  2. Importing a pre-existing text file

Add new table

Use the first option if you don't have a list of subjects ready as a text file or spreadsheet. This will just mean you have to enter the IDs manually as you do your QC.

Click Tables > Add New, and the following dialog will appear:

cortical_thickness_new_table_dialog.png

Use the "Add field" button to add the fields as above, and set their data types and sizes. Be sure to click the "IsKey" box for the "id" field, which will set this field as the table's key field. Click "OK" and your table will be created.

Import text file

If you already have a list of IDs, we can directly import these into a new ModelGUI table. If you don't, you can do this very simply in Linux with the command:

ls /path/to/civet/dir > /path/to/list.csv

Open/import the list in a spreadsheet program like Microsoft Excel, LibreOffice Calc, or Gnumeric. Add a row at the top and enter for column headers: "id", "qc", "rois", "comment". Finally, export the spreadsheet as a comma-delimited text file (csv).

To import, expand the "I/O" section and click "Import data". You'll see the following dialog box:

cortical_thickness_import_table_dialog.png

As shown, set the delimiter to a comma, check "First field is key", and then click "Choose files.." and select the csv file you created. We want to rename this file to "civet_qc", which can be done by clicking "Rename..". Finally, set the "data type" and "length" values as in the image above, and click OK. The table will be imported, and you'll have all your IDs already set.

Displaying the table

Right-click the QC window you created earlier and select "Set data table as source" to display the table you just created. You can now edit this table with your QC observations as you browse through the subject data. All changes to this table are immediate (i.e., do not have to be saved at any point).

Saving the data source

You can save your data source object so that it can be easily loaded later, using the Sources > Save button. Here, you have two options. If you want the data source to load automatically whenever you run ModelGUI, save the data source to the installation folder, under the subdirectory data_sources. If not, you can save it wherever you'd like and use the "Load" button to load it in the future.

Going further

  • You can use the snapshot functionality (right-click, Snapshot..) to output individual windows to image files.
  • You can also output videos; see this tutorial

Future improvements

One huge annoyance is that (most of) these steps have to be followed every time you run ModelGUI, including if the program is closed by accident or by crashing. The plan for the near future is to:

  1. Incorporate cortical thickness projects into the more generic Projects framework
  2. Allow all Projects to be saved as XML, so they can be set up once, and easily reloaded
  3. Allow all Sessions to be saved as XML, so that everything, including the Project, Shape Set, Windows, and Data Sources can be set up once, and easily reloaded
  4. Provide pre-defined Project templates for common pipelines, such as CIVET, Freesurfer, or the FSL library

With this in mind, keep track of ModelGUI updates. One way to do this is by adding our newsfeed: http://feeds.launchpad.net/modelgui/announcements.atom …this can be done via a RSS news feed reader, such as:

  • RSS Live Links (for Google Chrome)
  • Live Bookmarks (for Firefox) - Simply follow the link and add to your Bookmarks toolbar
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License