Next: 5 E. Diffusion Weighted Up: 4 D. Multi Subject/Multi Previous: 14. The Multi-Subject Control Contents

Subsections

15. The Data Tree Manager

15.1 Introduction

The Data Tree Manager Tool, shown in Figure 15.1 is a powerful utility for managing and working with whole sets of images, surfaces, transformations, and other data relevant to both clinical and research applications. All of the images and their relevant transformation files are stored in a configuration defined by a ``tree'' style hierarchy, allowing you to quickly visualize which transformations are available, and which need to be calculated in order to perform a given operation. Furthermore, multi-subject operations are easily automated, and associated data management facilities are included.

The top menubar of the Data Tree Manager contains menus that allow you to access the viewers directly (see Chapter 5), as well as the Registration tools which operate on the images contained in the viewers at any given time (see Chapter 10). Thus, the datatree is a convenient central organizing point for many of the operations that BioImage Suite performs.

**Figure 15.1:** The Data Tree Manager

15.2 The Tree

The hierarchy tree structure is the heart of the Datatree Manager. The following sections describe how to work with the tree structure and take advantage of its features.

Image Tree structure and function

**Figure 15.2:** The tree hierarchy. The images with purple brain icons exist, while those with grey icons have not been loaded. Similarly, transformation with green lines exists, while those with red lines have not been loaded.

The left hand panel of the Data Tree Manager, shown in Figure 15.2, displays the tree hierarchy. This panel is the most important part of the tool. It shows not only which files (images, surfaces, and transformations) have been loaded, but also these relationships between the images and surfaces. In this tree hierarchy, the images and surfaces are shown as nodes. A node located directly above another node is known as the parent of the second node while the second node is known as the child of the first node. Transformations are shown as the lines in between the nodes and must be computed for each parent-child pair. Once the transformation between a child and parent is computed, the child will inherit all of the transformations that can be applied to the parent. This relation between parents and children makes calculating several permutations of transformations easier and less time consuming.

Building a tree

The tree is built by adding children to already existing parents. As a result, the top parent in the tree, ``Data,'' cannot be deleted. As other nodes are added to the tree, sibling nodes are arranged in ASCII order. Thus, giving a node a name that begins with 0 will force that node to ahead of its siblings in the tree display. (A convenient naming convention is to begin all names with a number, allowing you to explicitly set display order).

**Figure 15.3:** Adding a Node to the Tree. Right clicking on an image node brings up this menu, from which you can choose to add an Image, an ROI Definition, or any of the Surface Types in the flyout.

15.2.0.1 Adding a node

To add a node to the tree, right-click on the existing node where you would like to add the new node as a child. A pop-up menu, shown in Figure 15.3, will appear, from which you may select ``Add an Image as Child,'' ``Add an ROI Definition,'' or ``Add a Surface as Child.'' The Surface choice has a flyout which allows you to add either a Surface, Electrode Grid, or Landmark Set. If you choose ``Add an Image as Child,'' a dialog box will appear with a list of standard choices for image modality. If you choose one of these, it will become the default title of the node. A custom title can be created via the entry box below the list. The advantage to selecting a title from the list is that the image type will be automatically set to an internal number convention. These conventions can be edited from the Options menu (See the section on Image Types). The newly added node is just a placeholder until the file that holds that actual image is specified.

The same menu as described above is available under the ``Image'' menu heading in the menubar. The commands in the menu will be performed relative to the currently selected node in the tree.

Specifying a Node's Filename

In the right-click pop-up menu or the ``Image'' menu in the menubar, select ``Set Filename.'' A file selection dialog box will appear. Once the filename has been set, the node will turn from gray to purple. Also, the file path will appear in the status bar when the node is selected.

15.2.0.2 Renaming and Deleting Nodes

To rename or delete a node, right-click on it. In the pop-up menu, select either ``Rename'' or ``Delete.'' If ``Rename'' is selected, a dialog box will appear asking for the new name for the node. The node will then either be renamed or deleted, and the tree will be rearranged to reflect the new order of nodes. Remember that the nodes are displayed in ASCII order. Numbers come first, capital letters come next, and lowercase letters come last.

Node Types

Image Image nodes are the most important type of node in the tree. Each one contains a single image file.

Folder A Folder node functions as a grouping mechanism, but has no significance in the calculation of transformations. It is inherently an identity; essentially ``passed over'' when concatenation of transformations is taking place. It can sit in the tree at any location, since it functions as an identity when being concatenated into the result transformation, if it is in intermediate in the transformation path.

Patient A Patient node is actually a ``folder'' containing all data for a given patient. What makes them different from a folder node is the fact that they can have an arbitrary array of subject measures attached to them, which can be useful for statistical comparisons etc. These properties are set in the Node Info Box for the patient nodes.

Surface A surface is a *.vtk file type that specifies a surface extracted from an image. Surfaces cannot be added as children of Patients or Folders (or the root).

Electrode An electrode grid is a special variety of surface that specifies electrode locations in the brain. These also can only be added as children of images.

Landmark A landmark definition is also a surface file that specifies any set of landmarks that you indicate. These also can only be added as children of images.

Atlas An atlas is a special type of image that specifies an anatomical atlas which has marked regions and a text file associated with it that identifies them. If an Atlas node is included in the tree and appropriately registered to its children, then the Atlas Tool can be used to navigate through any image registered to the atlas (directly or indirectly through the tree).

Results Results nodes are created by the program when multisubject calculations are performed.

ROI Definitions An ROI definition is a mask image that has discrete regions. These are used in multiple subject calculations. ROI definitions must be added explicitly as such, by using the ( Image | Add an ROI Definition ) menu option, or selecting that command from the right-click pop-up menu in the tree.

Note: The icons for some of the types can be changed in (View | Choose Icon Colors ). The flyouts have color choices for the brain icons.

Transformations and Identities

A transformation is simply the file generated by the registration process. It defines the function for mapping a point in one image or surface to the corresponding point in another image or surface. Bioimage Suite uses transformations stored in either *.matr files (linear transformations) or *.grd files (non-linear transformations). It is easy to see that linking nodes together with transformations is useful, since it allows you to significantly decrease the number of individual registrations that need to be calculated. Once the relationships in a chain of nodes are defined, and the transformations between parent and children are identified, any image or surface in the datatree can be mapped into the space of any other image or surface in the datatree. The tree hierarchy display shows this explicitly with the use of dynamically colored connecting lines.

15.2.0.2.1 Transformation Line Colors:

Each line represents two transformations; a transformation to the parent and a transformation from the parent. The color of the line that lies horizontally to the left of a node gives the information about the transformations to and from that node's parent. If the line is red, then neither transformation has been specified. If it is green, then both transformations have been specified. If the line is yellow, then only the transformation FROM the parent has been specified. If it is purple, then only the transformation TO the parent has been specified.

15.2.0.2.2 Specifying Transformations:

The transformation between parent and child nodes is specified at the child node. Right-click on the node, and select ``Load Transformation FROM Parent.'' A file selection dialog box will appear allowing you to choose the transformation file. For linear transformation, the transformation to the parent or inverse transform is automatically calculated and does not need to load into the datatree. However, the inverse of a non-linear transformation must be loaded independently of the original transformation. To load the inverse of a non-linear transformation, right-click on the child node, and select ``Load Transformation TO Parent.'' A file selection dialog box will appear allowing you to choose the transformation file. See Chapter 10 for more details on inverting transformations.

**Figure 15.4:** The Node Info Box. The name of the node is displayed as the title. Here you can get and set the filename of the image, as well as the transformations to and from its parent.

Node Info Dialog Box

Double-clicking on a node in the tree brings up the Node Info Dialog Box. The Node Info Dialog Box is shown in Figure 15.4.

15.2.0.2.3 Viewing the Node Info Dialog Box:

The node's icon and title are displayed at the top of the Node Info Dialog Box, and more detailed information about the node is available below. Here, you can view the node name, type, filename, and the filenames of the transformations that apply to the node. For the fields that specify a file associated with the node (``Filename,'' ``Transformation FROM Parent,'' and ``Transformation TO Parent,''), a button with an ellipsis (``...'') is placed next to the field. Once clicked on, a file selection dialog box appears, allowing the file to be set directly. This change will be reflected immediately. The large box at the bottom of the Node Info Dialog Box is a space for notes. Anything that is typed here will be saved when the Node Info Dialog is closed. All of this data is saved when you save a tree.

15.2.0.2.4 Extra Information for Patient Nodes:

The Node Info Dialog Box for patient nodes contains a set of customizable fields that can be set to contain any patient data that you would like to note. Currently there are no facilities for performing statistical calculations on images along with these values, but this will be implemented soon. To define which patient attributes you want to include, use ( Options | Edit Patient Property List ).

**Figure 15.5:** The Grab Box. This small dialog box allows you to grab any of the items in it from the corresponding data in either viewer and place it into the tree.
0.75

Grabbing an Image from the Viewer

If you want to add a node to the tree based on the image data that is currently displayed in the viewer, select a node in the tree for the parent and click the Grab Image From Viewer button (located at the bottom of the tree display). The image to be grabbed must be in the ``Image'' Display of the viewer (see Chapter 5). The Grab Box, the small dialog box shown in Figure 15.5, will pop up and show the different types of objects that you can grab from either of the two viewers. Simply click ``Image,'' ``Surface,'' ``Electrodes,'' or ``Landmarks,'' for the viewer you wish to grab from. A file selection box with the appropriate file type will appear, asking for the newly grabbed file to be saved. Once saved, the file will appear in the tree, as a child of the node that was initially selected initially. It will be named ``Grabbed_Image_*'' with * = some number to differentiate it from other grabbed images. The name can be renamed by using the ``Rename'' feature describe above. (You will still be able to create a file even if there is no data of the correct type in the viewer - a node will be added to the tree, but it will contain nothing).

Cutting and Pasting Parts of the Tree

If you want to move a part of the tree (subtree) to another part of the tree, or make a copy of the part, you can use the Cut, Copy, and Paste commands. These features are found in the Edit menu and work just like Cut, Copy, and Paste, in any text editor:

When you select a node and choose the ( Edit | Cut ) menu item, the node is deleted, and it is placed, along with its subtree of children, onto the clipboard.
When you select a node and choose the ( Edit | Copy ) menu item, a copy of the node and its children is placed onto to clipboard, but the node remains in place.
When you select a node and choose the ( Edit | Paste ) menu item, the contents of the clipboard are added to the tree as descendants of the currently selected node.

This is useful if you have a section of the tree that needs to be repeated over and over. You can simply copy and paste a set of images multiple times, making tree building much quicker than defining one image at a time.

15.3 Space, Anatomical, and Functional Images

The right side of the Data Tree Tool display, shown in Figure 15.6, shows the images that are currently being worked with, and potentially sent to the viewers. The three brain space represent images, surfaces, electrodes, or landmark data, and the two arrows represent transformations. Images are resliced into the coordinates of the image in the ``Space'' location. Most often, you will set the ``Space''and ``Anatomical'' images to be the same image. Thus, when an overlay is created, the image will appear in the coordinates of the image that is shown as the anatomy. The ``Functional'' image will be resliced into the space defined by the ``Space'' image, so that when displayed, the function data coincides with the correct anatomical loci, based on the registration.

15.3.0.0.1 What is Reslicing?

Reslicing is the process of sampling an image and creating a new image from it that has slices that coincide with the slices of another ``space defining'' image. For example, if the space defining image has one slice for every 1mm in its Z-axis, then any image resliced using this space definition will end up with one slice every 1mm in its Z-axis, regardless of which orientation the slices are in the original. The process of reslicing yields a pair of images in which X, Y, and Z coordinates correspond to the same location in the image, provided that the registration file that maps points from one to the other is valid. See the section on Transformations.

**Figure 15.6:** The Reslicer. The top ``Space'' section holds the image into whose space you want to reslice the other images. The other images are resliced to match its resolution and size.

Setting Images to be Resliced

To set the space defining image, simply select an image in the tree and click on the Set Space/Anatomical Image button at the top of the right side of the Datatree Manager. This will place the selected image into``Space'' and ``Anatomical'' spaces. The display shows two colorful generic brain images above the space title, and the name of the node across it. This lets you know that these slots in the reslicer are filled. textbfNote: the arrow between the two spaces turns green.

Clicking the Set Functional Image button places the selected node in the tree into the brain space labeled ``Functional''. Again, the colorful brain appears in the display, along with the name of the node that you chose.

If you want to set the Space and Anatomical Images separately, you should use the options in the bottom section of the Image menu on the menu bar (which mirrors the popup menu that appears when you right click on an image). Here you can choose Set As Space/Anatomical Image, Set As Functional Image , Set As Space ONLY , Set As Anatomical ONLY , or Set As Space and Functional . Thus, you can quickly set up any configuration of space, anatomical, and functional data from reslicing.

The Big Arrows: Concatenating Transformations

The large arrows in the right side display that point to the Space Image represent the concatenation of all required transformations that form the path from the Functional and Anatomical images. This visualization quickly shows whether transformation into reference space is available. If all required transformations have been specified in the tree for either pair of images, then the arrow connecting them will be green. If any transformation is missing, the arrow will be red. If you try to reslice two images when they are connected by a red arrow, you will receive an error message which will indicate the first missing transformation in the queue.

Reslicing - make it happen

In order to reslice images according to the configuration you specified by setting the ``Space'', ``Anatomical'', and ``Functional'' images, and connecting transformations, simply click the large Reslice button at the top of the right side of the Datatree Manager. The ``Anatomical'' image will be resliced into the coordinates of the ''Space'' image; then the ``Functional'' image will be resliced into the coordinates of the ``Space'' image. The results will not show up in a viewer immediately; they must be sent to a viewer by using the Overlay Tool. The Overlay Tool is located in the ``Overlay'' tab. (right under the Reslice button).

**Figure 15.7:** The Overlay Tab. The overlay tab in the right side window of the Datatree Manager allows you to create views of functional data ontop of anatomical data with a number of optional settings.
0.87

15.4 The Overlay Tab

The ``Overlay'' tab, shown in Figure 15.7, contains the tools that allow you to combine two images in a meaningful way, taking advantage of the registration file that links them, as specified in the tree. The functional data can be overlaid on the anatomical data, creating ``hotspots'' of color on a gray background (the color scheme, including the anatomical colors, can be changed with the Colormap Editor).

15.4.1 The Reslice Output Box

The output of the reslicing operation is sent directly to the ``Overlay'' tab. This operation is indicated by the update of the Reslice Output box to show the combination of two images into the space of a third (which often matches the anatomical - see Reslicing). The presence of the colored brain icon image in this box tells you that an overlay image is in memory is ready to be sent to a viewer. To send an overlay to a viewer, just choose a viewer from the ``Output Viewer'' menu at the bottom of the Overlay Tab (Transform Viewer is the default). Then click the Create Overlay! button, and the image will be shipped to the viewer for further analysis or display (see Chapter 5).

15.4.1.1 Thresholding the Overlay

The next most commonly used tool in the ``Overlay'' Tab is the Threshold function. The ``Low Threshold'' and ``High Threshold'' sliders allow you to apply a threshold to the functional data before it is overlayed on the anatomical image. Simply set these slider bars, whose range will be automatically set by the range of intensities in your images, and click the Create Overlay! button.

15.5 Multiple Image Calculations

One of the advantages of the tree tool is that it brings all your data together in one place, and lets you work with all of your images and other data in the space of any other image in the tree. This functionality is very useful when it comes to doing group comparisons, averaging, and other multiple image operations.

Pre-processing

Before doing calculations on a group of images, they must be registered and arranged in the tree, as described in the Registration page, and in The Tree, above. Then you must select which space you would like to perform the calculations in. The rest of the images will be transformed TO this space before comparisons and calculations are made. Set the image you want to use to define the space and set it as the ``Space'' image (using either the Set Space/Anatomical Imag button, the Image menu, or the pop-up menu in the tree.

The Multiple Image Search Dialog

All multiple image calculations are performed from the ``Multiple Image Search Dialog'', which is available in the Tools menu and shown in Figure 15.8. The steps required are simple: Define which Images should be operated upon, and click the button to perform the operation!

**Figure 15.8:** The Search Box. This dialog box is accessed via the ( Tools | Multiple Image Calculations ) menu option. It contains fields for searching the tree for images by name, type, or containing folder. The results can then be fed into image statistics tools.

Choosing your images

The top section of the dialog box (See Figure ) is devoted to searching the tree. The images that will be operated on are those images that are in the ``Results'' section and are selected . There are three ways you can define which images to include, and they are complementary. Thus, you can search by image type, image title, containing folder, or any combination of these.

The ``Filter by Modality'' section contains a list of the image types currently defined (See Image Types). You can select one type by clicking on it in the list, or multiple types with Ctrl-clicking. Then click the Search! button. All images of that type will be placed in the ``Results'' list, and selected by default. If you do not want to select any image types, just Ctrl-click on the selected item in this list, and the selection will disappear, meaning that all image types will be included in the search.
If you specify a search string in the ``Filter by Title'' entry field, only nodes that match this title will be placed in the ``Results'' list when you hit the Search! button. If you leave it blank, all titles will be included in the search.
You can select a folder in the tree to search. Click the ``...'' button in the ``Specify Folder(s)'' section, which will bring up a list dialog box containing all the folder names present in the tree. Select one (or more with Ctrl-click) folder(s) in the list and click OK. Now, only nodes within the folders selected will be included in the search.

Once you have a list of nodes in the ``Results'' section, you can manually select those upon which you want to do some calculations. By default, all items in the ``Results'' list are selected, but you can deselect them one at a time by just left-clicking on them.

Doing the Calculations

The functions that are available in the lower half of the dialog box are subject to change, since we often identify new multiple image calculations that are useful. To perform any of these calculations, just click the button!

15.5.0.0.1 Save All Images in Reference Space:

This button queries the user for a directory, and then saves a copy of each result image, transformed to the reference space (as set in the main window).

15.5.0.0.2 Average Images in Reference Space:

This button transforms all images to reference space, and then averages them, creating three result images, which are saved, and placed automatically into a folder in the tree: Average, STD Dev, and T-map. These three images are in the space of the ``Space'' Image, and thus the folder is created as a child of this image.

15.5.0.0.3 Compute ROI Stats in Reference Space:

This function relies on there being an ROI definition image in the tree and linked to the other images by valid transformations. When you click this button, the program will search the tree for all ROI definition images (which must be added as this type specifically - see the bottom of the Node Types box). A list dialog box will appear, in which you should select just one ROI image. This ROI image, along with all the ``Results'' images will be transformed to the reference space, and statistics will be computed in each image for each region defined in the ROI image. The output is a tab-delimited text file, which you will be prompted automatically to save. This numerical output will also be displayed in a console window that pops up.

15.6 Functionality for Intracranial Electrode Attributes

An Electrode Node (see Node Types) is meant to have a *.mgrid file loaded into it. These files specify the locations of a set of electrodes. Once you have loaded an *.mgrid file, you can send it to the Electrode Control, which will allow you to display the electrodes over the image that is in the Transform viewer. The Electrode Control does not send electrodes to the Reference viewer, so if you want to work with an electrode file in relation to your image, send the image to the Transform viewer.

The Electrode Menu

**Figure 15.9:** The Electrode Menu. This menu appears when you right-click on an electrode node. It contains features for working with electrode objects.

The following menu commands are available for electrode nodes:

Set Filename: As for all nodes, this allows you to load an file, to which this node will become a pointer.
Attribute Visualization Control: Sends the node's attributes to the visualization control, described below.
Load Attributes: Load an electrode attribute file for the node (see next section.
Update Attributes from Viewer Electrodes: Sets the nodes attribute array to that of the electrode file currently displayed in the viewer.
Rename: Changes the title of the node.
Delete: Deletes the node from the tree.
Send to Electrode Control (1 or 2): Sends the node's electrode data to one the two electrode controls that are linked to the Transform Viewer (Viewer 2). Both Electrode Control 1 and 2 show their electrodes in Viewer 2. Thus, two sets of electrodes can be displayed in the Transform Viewer simultaneously.
Send to Electrode Control (1 or 2) in Reference Space: Same as above, except the transformations from the electrode node to whatever image is set as space are applied to the electrode object first.

Electrode Attributes

15.6.0.0.1 What are they?:

Electrode attributes are simply a binary array that gets attached to an electrode node, and contains flexible information, as directed by an imported loadfile. Simply put, this function allows you to create ``categorized'' electrodes, and differentiate between them visually and via region of interest calculations.

An example would be instructive: The table below shows an example theoretical structure for an attribute definition for a given set of electrodes.

Elec. # Elec. Name On Surface Depth Gamma Increase Gamma Decrease

1 A1 1 0 0 1

2 A3 1 0 1 0

3 A8 1 0 0 1

4 B1 0 1 0 1

5 B2 0 1 0 1

6 B3 1 0 1 0

7 B4 1 0 1 0

8 C6 1 0 1 0

9 D2 1 0 1 0

And so on..

Elec. #	Elec. Name	On Surface	Depth	Gamma Increase	Gamma Decrease
1	A1	1	0	0	1
2	A3	1	0	1	0
3	A8	1	0	0	1
4	B1	0	1	0	1
5	B2	0	1	0	1
6	B3	1	0	1	0
7	B4	1	0	1	0
8	C6	1	0	1	0
9	D2	1	0	1	0
And so on..

The electrode numbers and names in the set of electrode attributes to be loaded must correspond exactly with the electrode names of the *.mgrid file it will be associated with. The rest of the fields are completely customizable (thus, you can name the various headings anything you like - simply by editing the electrode attribute load file).

Loading Electrode Attributes

In order to load the attributes for the Electrode Attribute dialog box, you need to place them into a tab-delimited file (you should be able to cut and paste from a spreadsheet, for example) with a header that matches the ``electrode attribute template'', which looks like this:

 
#Electrode Attribute Description File 
#---------------------------------------------------------------------------------------------------- 
# (space or tab delimited) 
 electrode# name brain exclude theta_up theta_down beta_up beta_down gamma_up 
#----------------------------------------------------------------------------------------------------

You can either create a new text file by cutting and pasting the above, or find the header in the template file ElectrodeAttributeTemplate.ele , in the same directory as the DataTree executables.

**Figure 15.10:** The Electrode Attribute Tool. Here we see the tool, accessed via the electrode menu, which allows users to create overlays showing electrodes with differing properties in different layers.

The Attribute Visualization Control

The function of the attribute visualization control is very simple, it creates an overlay image out of a space image and an electrode file, based on the properties specified by the electrodes' attributes. Thus, a 4D image is created, with the regions on any given layer corresponding to all the electrodes that share the property in the corresponding column. The checkboxes present in the top part of the window represent the attributes that are set, and will change depending on the attribute file that you load. The utility of this is that you can create a different image for any combination of 1 or more attributes. Simply check the boxes of the attributes that you want included in the overlay image, and push the Create Electrode Overlay Image! button. The appropriate transformations will be applied, and small spots representing the electrodes will be overlayed on the Space Image (whose filename is displayed for reference in the bottom field of this dialog box). Note: As with many operations in the Data Tree tool, the space image must be set for the attribute visualization control to work,

The resulting image is appropriate for use as a ROI definition image, in order to quantify regions of overlap between electrodes and functional data.

15.7 Options

Lock the Space Image

This disables changing of the ``Space Image'' (see Setting the Reslicer Images). This is useful if you know that you are going to want to always warp your images to the same space, and want to avoid accidentally changing it.

Image Types

Each image type is set by a number (the default image type group ranges from 10 to 9200, but you can choose any whole number scheme you want). These numbers are arbitrary, and only serve as tags to help with searching. The numbers and associated list of image types are completely customizable, so that when you add images to the tree, the list of image types available can reflect your study's image types.

Patient Properties

Choosing the ( Options | Edit Patient Property List ) menu option brings up a small list dialog box that has a simple list of attributes that will be shown in the node info dialog box for each patient node.

Next: 5 E. Diffusion Weighted Up: 4 D. Multi Subject/Multi Previous: 14. The Multi-Subject Control Contents