The Data Tree Manager




Introduction

 The Data Tree Manager Tool is a powerful utility for managing and working with whole sets of images, spaces, surfaces, and other data relevant to both clinical and research applications. All of the images and their relevant registration 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 Viewers), as well as the registration tools which operate on the images contained in the viewers at any given time (see Registration). Thus, the datatree is a convenient central organizing point for many of the operations that BioImage Suite performs.


The Tree

Image Tree structure and function

Fig. 1 An example tree hierarchy.
The Images with purple brain icons exist, while those with grey icons have not been loaded. Notice the red and green connecting lines. The green lines indicate that a transformation is possible in both directions between the two images it connects. The red lines indicate that no registration has been loaded for the two nodes. You can build a hierarchy in any configuration that you want. The only restraints are in the registrations that you have (or want to have) calculated. Build your tree so that there are a minimal number of non-rigid registrations involved, and use the automatic concatenation function of the tree to warp images into common spaces.

The left hand panel of the surgery tool display contains the tree hierarchy. This is the most imporatant part of the tool, since it shows which image files (and other types of files) have been loaded, which registrations have been loaded, and what their relationship is to one another. It would be very tedious to register all images to each other in every permutation. This is avoided by arranging the images in a hierarchy. The transformations from children to immediate parents must be calculated, but any further transformation up the tree will be automatically generated by concatenating the intervening transformation. Furthermore, if the transformation is linear (specified by a 4x4 matrix), then the inverse is automatically created.

Building a tree

 You build the tree by adding children to already existing parents. Thus, the top node in the tree, "Data," cannot be deleted. As nodes are added to the tree, they are arranged in ASCII order. Thus, to force a node to the top of the tree display, give it a name that begins with 0. (A convenient naming convention is to begin all names with a number, allowing you to explicitly set display order).

Adding a node

To add a node to the tree, right-click on an existing node, to which you would like to add the new node as a child. A pop-up menu will appear (See Fig 2.), 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. You can also create a custom title 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. You can edit these conventions from the Options menu (See the section on Image Types). Note: a newly added node is just a placeholder until you specify the file that holds that actual image (See below).

The same menu as the pop-up that appears when an Image node is selected 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.

To add an Atlas node to the tree, you must select "Add Atlas to Tree at Selection" from the "Atlas" menu (See the Atlas Section).

Specifying a node's Filename

In the node's pop-up or menubar menu, select Set Filename. A file selection dialog box will appear. Once the filename has been set, the file path will appear in the status bar when the node is selected.

Renaming and Deleting Nodes

To rename a node, right-click on it. This will bring up the node menu. Select "Rename." A Dialog box will appear asking for you to type the new name for the node. When you click OK, the node will be renamed, and the tree will be redrawn to reflect the new order of nodes. Remember that the nodes are displayed in ASCII order. Thus, numbers come first. Capital letters come next (in alphabetical order), followed by lowercase letters in alphabetical order.


Node Types

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

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 aribitrary array of subject measures attached to them, whic can be useful for statistical comparisons etc. These properties are set in the Node Info Box for the patient nodes.

Fig. 2 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.



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 concatentated into the result transformation, if it is in intermediate in the transformation path.

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. The same parent rules apply as for Surfaces and Electrodes.

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. They must be added explicitly as such, by using the ( Image | Add an ROI Definition ) menu option, or selecting that command from the pop-up 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 to the corresponding point in another image. Bioimage Suite uses transformations stored in either *.matr files (linear transformations) or *.grd files (non-linear transformations). It is easy to see that linking chains of images 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 images are defined, and the transformations between them are identified, points in any image in the chain can be mapped into the space of any other image in the chain. The tree hierarchy display shows this explicitly with the use of dynamically colored connecting lines.

Transformation Line Colors

The color of the line that lies horizonally 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 are specified. If the line is yellow, then only the transformation FROM the parent has been loaded. If it is purple, then only the transformation TO the parent is specified.

Specifying Transformations

The transformation between two images in the tree is specified at the child node. Right-click on the node, and select "Load Transformation FROM Parent" or "Load Transformation TO Parent (if non-linear)," depending on which you have calculated (See Registration). A file selection dialog box will appear allowing you to choose the transformation file. If the file you select is linear (*.matr), then the inverse will automatically be calculated and loaded in to the opposite transformation. Thus, the node's line will become green. If the transformation is non-linear (*.grd), then transformations in only one direction will be available until you load the other transformation file.

Fig. 3 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.

Getting and Setting Node Information

 Double-clicking on a node in the tree brings up the Node Info Dialog Box. The node's icon and title are displayed at the top, 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. If you click it, a file selection dialog box appears, allowing you to set the file 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 you type here will be saved when the Node Info Dialog is closed. All of this data is saved when you save a tree.

Extra Info 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 make note of. 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 ).

Fig. 4 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.

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 viewer's "Image" Display (see Image Display vs. Results Display). A small dialog box will pop up showing 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 you to save the newly grabbed file. Once saved, the file will appear in the tree, as a child of the node that you selected initially. It will be named "Grabbed_Image_*" with * = some number to differentiate it from other grabbed images. You can then rename the grabbed image to anything you like, by right clicking on the image and selecting "Rename." (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 are found in the Edit menu. They work just like Cut, Copy, and Paste, in any text editor: This is useful if you have a section of the tree that needs to be repeated over an over, once for each of a group of subjects, for example. You can simply copy and paste a set of images multiple times, making tree building much quicker than defining one image at a time.

Space, Anatomical, and Functional Images

 The right side of the Surgery Tool display shows the images that are currently being worked with, and potentially sent to the viewers. The three brain spaces represent image, space, electrode, or landmark data, and the two arrows represent transformation data. This is where reslicing happens. Images are resliced into the space 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 space 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, its data coincides with the correct anatomical loci, based on the registration.


What is Reslicing?

Reslicing is the process of sampling an image's values 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 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.


Fig. 5 The Reslicer
The top "Space" space holds the image into whose space you want to reslice the other images. The other images are resliced to match its resolution and size, thus allowing you to create an overlay of functional data on anatomical data, among other things. Note that the top left button sets both the Space and the Anatomical images to the selected image in the tree. (Use the pop-up menus to set them individually.)

Setting the Reslicer Images

 To set the space defining image ("Space"), 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 Surgery Tool. This will place the selected image into the brain spaces "Space" and "Anatomical". The display shows two colorful generic brain images in the spaces, and the name of the node across it. This lets you know that these slots in the reslicer are filled. Note that 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 labelled "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: Concatentating 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 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 via the required connecting transformations, simply click the large Reslice button at the top of the right side of the surgery tool. The anatomical image will be resliced into the space of the space-defining image; then the functional image will be resliced into this same space. The results will not show up in a viewer immediately; they will be sent to the overlay tool, which can be accessed by clicking on the "Overlay" tab (right under the Reslice button).

Fig. 7 The Overlay Tab
The overlay tab in the right side window of the surgery tool allows you to create views of functional data ontop of anatomical data with a number of optional settings.

The Overlay Tab

 The overlay tab 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). Once you have clicked the Reslice button, the overlay image can be sent directly to the viewers from the overlay tab. Simply choose a viewer in the "Output Viewer" menu at the bottom (See figure), and click the Create Overlay! button. There are, however, a number of other important options that you can set from the overlay tab, and pieces of information that you can get here.

The Reslice Output Box

The output of the reslicing operation is sent directly to the overlay tab. This 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 there is an overlay image in memory that is ready to be sent to a viewer.

Send Overlay Image to a Viewer

In many cases, all you need to do to view your overlay image properly is send the reslice output directly to one of the viewers. To do this, just choose a viewer from the 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 The Viewers).

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.





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 decribed in the Registation 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 Image button, the Image menu, or the pop-up menu in the tree.

The Multiple Image Search Dialog

Fig. 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.

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

Choosing your images

The top section of the dialog box (See Figure 8) 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.

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!

Save All Images in Reference Space

This 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).

Average Images in Reference Space

This 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.

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.




Electrodes

 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 Transformation 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

Fig. 8 The Electrode Menu
This menu appears when you right-click on an electrode node. It contains a few options, described at left, 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: Change the title of the node Delete: Self-explanatory: delete the node from the tree.
Send to Electrode Control (1 or 2): Send the node's electrode data to one the two electrode controls that are linked to the Transform Viewer (Viewer 2). That's right, 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

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
1A11001
2A31010
3A81001
4B10101
5B20101
6B31010
7B41010
8C61010
9D21010
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.

Fig. 9 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 Visulization Control

 The function of the attribute visualiztion 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 approprate 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 qunatify regions of overlap between electrodes and functional data.





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 arbirary, 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.




About this manual.