Working with data
1.0 Anatomical volumes
1.1 Main and aux volumes
Tkmedit can hold two anatomical volumes in memory at the same time, called the Main volume and the Aux volume. Although it can not display them together at the same time, clicking on a voxel in one volume will display that value at that voxel in both volumes.
The Main volume is considered the central data object in tkmedit. All other data is displayed relative to the Main volume. The subject name and Main volume name are displayed in the title bar of the Display Window. If an Aux volume is loaded, its name is displayed in parentheses next to the Main volume name in the title bar.
If both volumes are loaded, you may select which volume is displayed by choosing Main Volume or Aux Volume in the View menu, or by pushing in the appropriate button ( for Main and for Aux) on the Main Toolbar. The currently shown volume will be surrounded by double asterisks in the title bar, and its value in the Tool WIndow is shown in double asterisks. If only the Main volume is loaded, asterisks will not be displayed.
You can go to a specific location in the volume by using the Tools, Goto Point... command, or by typing the coordinates into one of the fields in the Tools Window where the coordinates are displayed and pressing the return key.
1.2 Display transform
Display transforms can be applied to each volume to transform its position. This transform only affects the way the volume is drawn in the Display Window. All coordinates displayed in the Tools Window will not be affected by this transform.
The file must be an LTA (*.lta) or XFM (*.xfm) transform type. To load a transform for the Main volume, choose File, Transforms, Load Transform for Main Volume... from the menu and enter the file name of the transform. To unload it, choose File, Transforms, Unload Transform for Main Volume. There are corresponding items for the Aux volume.
1.3 Display options
Volume display in tkmedit is pretty basic, but there are options for configuring the brightness and contrast of each volume. Choose View, Configure, Brightness / Contrast... to open a dialog with four sliders. The top two control the brightness and contrast of the Main volume and the bottom two the Aux volume.
You may also turn off the volume display by unchecking View, Anatomical Volume. This is useful if you want to look at other types of data with the anatomical volume in the background. Neither the Main nor Aux volume will be displayed if this item is not checked.
You can display a maximum intensity projection by checking the View, Maximum Intensity Projection item. This displays the voxel with the highest value in the current orientation, and is the same for every slice in an orientation.
Editing is done with the Edit Tool which can be activated by pushing the button in the Main Toolbar, by choosing Tools, Edit Voxels, by pressing the 'a' key.
There are settings for two 'colors' for this tool, each bound to a button when this tool is active. These settings can be choosing Tools, Configure Volume Brush.... This tool, along with the other editing tools, uses the global brush settings available in Tools, Configure Brush Shape... and in the Reconstruction Toolbar. These include the shape of the brush ( circular or square), its radius, and whether or not it acts in all three dimensions (). You can also select whether your edits affect only the Main volume or both the Main and Aux volumes. (Most users will only want to edit one volume.) If the Main volume is the only target and even if the Aux volume is visible, the Main volume will still be edited.
This brush uses a threshold that allows you to specify which voxel values to be affected. This allows you to change ranges of values in an area to a new value, useful in cleaning up large anatomical areas.
There are a few other operations you can use to edit the volume. In the Tools, Volume menu there are commands for Thresholding, Flipping, and Rotating the volume. These are self-explanatory and can be used to fix misoriented data. These operations only affect the Main volume only.
The Smart Cut command is designed for removing entire chunks of volume based on the position of the cursor. It will create a cutting plane perpendicular to the current viewing orientation based on the closest edge of the window and remove everything from that plane to the edge. For example, if you place the cursor near the bottom-middle of the screen and activate the command, it will remove everything from the cursor to the bottom edge.
There are three ways to undo an edit. All of them only work with the Main volume, as it is the only one that can be edited. The first is with the standard Edit, Undo Last Edit menu item. This action will undo the last edit, and is the quickest and easiest way to undo single edits.
Another way is to use the Snapshot Volume tool in the Tools, Volume menu. Take a snapshot of the volume to save a copy of its contents in memory by choosing Edit, Take Snapshot of Volume. To restore the volume to this state, use the Edit, Restore Volume to Snapshot tool. This method is ideal for making 'milestone' versions of the the volume state. There are buttons for these commands on the Reconstruction Toolbar: for taking a snapshot, and for restoring to it.
The third way is to use the Undo Volume. This can be envisioned as a separate volume containing all the voxels that have been changed. You can view these voxels by checking View, Undoable Voxels; they will be drawn with a blue highlight. By holding down the shift key and clicking with mouse button 2 with the Edit Voxel tool active on an undoable voxel in Display Window, you can undo all contiguous undoable voxels, like an undo flood fill. This is best suited for undoing contiguous areas of voxels.
After all your careful edits, you will want to save the changes to your data. tkmedit writes anatomical volumes out as COR- files. Choose File, Save Main Volume to overwrite the original source volume or File, Save Main Volume As... to specify a new location. You can save the Aux volume with corresponding commands in the File, Aux Volume submenu.
2.0 Control points
Control points are used in surface construction. Every subject has an associated control.dat file in their tmp directory; this is the list of control points, in TalairachSpace, that is read in to tkmedit automatically upon start.
2.1 Display options
Control points appear as green cross hairs in the Display Window. They can be turned off by unchecking View->Control Points.
2.2 Making and deleting control points
Control points can be edited with the Edit Control Points tool, which can be activated by pushing the button on the Main Toolbar, by choosing Tools->Edit Control Points, or by pressing the 'c' key when the mouse is in the Display Window.
To make a new control point, click anywhere in the Display Window with mouse button 2. To remove a control point, click near it with mouse button 3. Button 3 will remove the closest control point to the voxel clicked, within 3 voxels.
Whenever a new control point is made, it is automatically written to the control.dat file. However, removed control points are not removed from the file until you choose File->Save Control Points or quit normally with the File->Quit command.
Selections are also called labels or ROIs. You can read or write selections from and to label files or create them from within tkmedit. Note that there is only one selection in tkmedit, even though it doesn't have to be contiguous.
3.1 Display options
Selections are drawn as a green overlay. This overlay can be turned off by unchecking View, Selection / Label.
3.2 Selecting and deselecting
You can select and deselect voxels with the Select Voxels Tool, which can be activated by pushing the button on the Main Toolbar, by choosing Tools, Select Voxels, or by pressing the 's' key.
This tool is a brush tool, so it uses the global brush settings available in Tools, Configure Brush Shape... and in the Reconstruction Toolbar. You can think of selecting and deselecting voxels as painting your selection. To select voxels, use mouse button 2 to draw your selection and button 3 to erase it.
You can also use a flood fill to select and deselect contiguous areas. Open the configuration dialog box with the Tools, Configure Flood Select...command. Here, you have options for the making the fill 2D or 3D, settings the source, and the fuzziness and distance parameters.
Source Volume: Specifies which volume to use when looking for similar voxels, so that the Main, Aux, or segmentation volumes can be used to look for regions.
Fuzziness: Determines the level of similarity to consider when finding regions. If it is 0, only voxels with exactly the same value as the voxel clicked will be set. If it is greater than 0, this is the maximum value difference from the clicked voxel that a contiguous voxel can have to be considered in the same region.
Distance: Determines the maximum size of the region to fill from the clicked voxel. If it is 0, there will be no distance limit.
3D: Determines if the fill is in-plane only or will fill in three dimensions.
Once you have configured your fill, perform it with shift-mouse button-2 or 3; 2 will select an area, and 3 will deselect an area.
3.3 Saving and loading
Tkmedit reads and writes label files. This file format is basically a list of points in RAS coordinate space with some header information. They can be loaded into tksurfer if they intersect with a surface.
Tkmedit can read and display 3D surface files. The surfaces are intersected with the displayed slices and drawn overlaid onto the anatomical data.
4.1 Surface configurations
There are three possible surface configurations: Main, Original, and Pial. When you first load a surface, it is read into the Main configuration, and tkmedit looks for the other two configurations with similar names.
You can manually load in another surface as the Original or Pial configuration. All three configurations can be displayed at the same time, so you can compare how a surface looks in relation to another one.
4.2 Loading and unloading
Use the File, Load Main Surface... command to load in the Main configuration. This will also try and load Original and Pial versions of this surface. Use the File, Load Surface Configuration... submenu to load the Original Vertices or Pial Vertices manually.
Surfaces take up a lot of memory and they some time to intersect and draw. To release these resources when you are done with a surface, use the File, Unload Surface command.
4.3 Display options
Each configuration is drawn in a different color. By default, the Main surface is drawn in yellow, the Original surface in green, and the Pial surface in red. You can change these colors in the View, Configure..., Surface... dialog box. You can also configure the width of the line used to draw the surface.
You can turn off surface display by unchecking the View, Main Surface, View, Original Surface, and View, Pial Surface items. You can also hide and show the surfaces with the buttons on the Reconstruction Toolbar ( Main surface, Original surface, and Pial surface). You can display the actual vertices of the surface by checking the View, Surface Vertices option.
There are two ways of determining which points to draw when intersecting the surface with the current slice; by using interpolation, and by using projection. Using interpolation will produce a smoother picture and a truer view of the surface intersection. However, the vertices that are drawn will be the interpolated intersection points of an edge and the slice, not the actual vertex. When projection is used, the vertices drawn will appear in their actual place in-plane. This diagram illustrates the methods better:
When View, Interpolate Surface Vertices is checked, the interpolation method is used. When it is unchecked, the projection method is used.
4.4 Finding and showing vertices
Tkmedit has a few tools for finding and displaying specific surface vertices. If you know the vertex number of the vertex you are interested in, you can use the Tools, Surface, Find Main Vertex... command to enter the number and go to that vertex. Note that if the edge width is smaller than the slice width, the vertex may be 'embedded' in the slice and the cursor will not appear right over a vertex. There are corresponding commands for the Original and Pial surfaces as well.
You can also have tkmedit find the surface vertex closest to the cursor with the Tools, Surface, Show Nearest Main Vertex command. The vertex information will be printed to the console. There are corresponding commands for the Original and Pial surfaces as well.
5.0 Functional volumes
Functional data can be viewed in tkmedit as an overlay onto the anatomical data (or any other volumetric data) or in a graph, as in a time course. Tkmedit can hold one volume for each purpose in memory at the same time. The volumes can be the same, i.e. a volume can be viewed as an overlay and as a time course, or separate.
5.1 Loading data
Loading Overlay and Time Course data is similar. Use the File, Load Overlay Data... or File, Load Time Course Data... command to load in a functional volume.
You can specify a registration file to use. If you do not, tkmedit will look in the same directory as the bfile data for a file called register.dat. A registration file is a matrix that defines the translation between anatomical RAS space and functional RAS space. Tkmedit uses this to align the functional volume with the anatomical volume.
The Time Course volume can also have an offset volume. This must be specified from the command line. See the reference section for details.
5.2.1 Display options
The Overlay is displayed, as implied in its name, as a translucent overlay in the Display Window. Its default state uses a heat color scale, in which negative values are drawn in blue and positive values are drawn in red. A threshold is used to limit the values shown and define a color ramp so that more values close to the maximum or negative maximum are red or blue and values close to the minimum or negative minimum are yellow or teal.
The Overlay display can be turned off by unchecking the View, Functional Overlay option. Other aspects of the Overlay display are configured in the dialog box available in View, Configure..., Functional Overlay.... The following options are shown:
Time Point / Condition: Changes the currently shown time point or condition in the Display Window. The range is shown in parentheses next to the label. Note that a header file must be present in order to specify the division of data between time points in conditions, otherwise tkmedit assumes multiple time points and no conditions.
Truncate negative / positive values: Check to turn off the display of negative or positive values.
Reverse values: Check to display negative values in red and positive values in blue.
Grayscale: Check to use a grayscale color scale instead of the normal blue to red heat color scale. The lowest, most negative values will be shown in black and the highest, most positive values in white.
Opaque: Check to make the Overlay opaque.
Ignore threshold: Check to display all the values in the volume with a linear threshold, disabling the threshold values.
Threshold minimum / midpoint / slope: Configures the heat scale display. The minimum is the lowest value shown. The maximum is defined by ( (1/slope) + midpoint ).
Note that the Apply button must be clicked for changes to take effect.
The View, Mask to Functional Overlay option is available to only draw areas of the anatomical volume that are in the valid space of the Overlay volume. This gives you a better sense of the entire Overlay volume and how it relates to the anatomical volume.
If enabled, you can use tkmedit to register the Overlay volume, or align the Overlay volume with the anatomical data. This changes the registration file. Use the Tools, fMRI, Register Functional Overlay command to bring up a dialog box containing arrow buttons. Use these buttons along with the associated parameters to move the Overlay volume.
You can save your changes to the registration file with the File, Save Overlay Registration item. You can restore the registration to its original state with the Tools, fMRI, Restore Overlay Registration. Use the Tools, fMRI, Set Registration to Identity command to set the registration matrix to the identity matrix.
Note that since registration can affect the validity of any data analysis you perform, the MGH-NMR processing stream only allows registration at a specific point in the stream. Registration may not be available at all times. It can be enabled from the command line at start-up time. See the reference section for details.
5.3 Time course
The Time Course is displayed in a separate graph window. The graph will only be shown if the Time Course volume has more than one time point. Clicking on a voxel in the Display Window finds the corresponding functional voxel based on the registration and displays the values at that voxel for all time points in the graph window.
If there are multiple conditions defined in the header file, each condition will show up as a separate line in the graph. The legend on the right side of the graph window displays what line corresponds to what condition. By moving the mouse over a condition label in the legend, the corresponding line in the graph will be highlighted. This is useful for picking out one condition in a crowded graph.
You can also zoom into the graph. Click and drag with button 2 to draw a box around the area of interest. The graph will be resized around that box. Click with button 3 to zoom back out.
If the same volume is being used for the Overlay and the Time Course, clicking in the graph window will change the time point in the Overlay display to what x point was clicked. You can use this method to navigate the Overlay volume.
The selection / label can be used to specify an average area to graph. To graph a selection / label as an average, draw or load a selection and choose Tools, fMRI, Graph Current Selection. The title at the top of the graph will change to show that a selection is being graphed instead of a single voxel. The contents of a selection can be printed to a text file in a chart form with the Tools, fMRI, Print Time Course Summary to File... command. You can use this data in a separate graphic program.
The contents of the graph window can be written to a Postscript file with the Tools, fMRI, Save Time Course Graph to Postscript File... command. It can then be included in another document or printed.
5.3.2 Display options
The graph can be configured with the View, Configure..., Time Course Graph dialog box. The top part of this dialog is a list of mappings between colors and conditions. You will see as many rows as the Time Course volume has conditions. You can assign a color to each condition with the number field on the right or hide colors / conditions with the checkbox on the left. By default, condition 0 is hidden. You can also enter a name for the color in the column on the left. This name will show up in the graph window in the legend on the right.
The bottom part has the following options:
Show error bars: If this box is checked and error data is present, vertical errors bars will be drawn at each data point, signifying the possible error for each value.
Automatically size graph: If checked, the graph axes will automatically resize according to the range of values. If unchecked, the axes will stay static.
Subtract pre-stim average: If checked, the average value of the values before the stimulus (time second = 0) for each condition is subtracted from all values. This effectively adjusts the y axis to normalize for pre-stim values.
Show percent change: If an offset volume is available, this will show the percent change for each value instead of the raw value itself.
Number of pre-stim points: Originally defined by the header file, this value lets you adjust the time = 0 value.
Time resolution: This is defined by the header file and is used to calculate how many seconds are in each time point.
Note that the Apply button must be clicked for changes to take effect.
A segmentation is a volume whose values represent an index of an anatomical structure or label to which the corresponding voxel in the main anatomical volume belongs. The structures are listed in a lookup table. This table also specifies the colors the structures should appear in, and is more commonly called a color table.
Both a volume and a color table must be loaded to view a segmentation. A segmentation data file is treated the same as a normal anatomical volume, so it can be a COR- volume or any other supported file type. The color table assigns a name and color to each index. You can load both items by choosing File, Load Segmentation....
You can create a new segmentation with the File, New Segmentation... command. You will still need to enter a color table to use.
You can import a surface annotation with the File, Import Surface Annotation as Segmentation... command. A surface annotation is a segmentation of the surface, so that every vertex in the surface has an associated label. Tkmedit will look up the corresponding voxel for each vertex and assign the label value to that voxel in a new segmentation.
Like the anatomical volumes, tkmedit can have a Main or Aux segmentation. Each can have its own color table. To load Aux segmentations use the commands in File, Aux Segmentation. As with the anatomical volumes, only the Main segmentation volume can be edited.
6.2 Display options
Segmentations are drawn as a colored overlay in the Display Window. The colors are defined in the color lookup table file specified at load time. The opacity of the overlay can be configured in the dialog box brought up by choosing View, Configure..., Segmentation Display.... overlay can be hidden by unchecking View, Segmentation Overlay. You can toggle between the Main and Aux segmentations with the View, Aux Segmentation Overlay command.
If the Segmentation Label Volume Count option in the View menu is checked, when the Edit Segmentation tool is active and the left button is used to set the cursor, tkmedit will count the number of contiguous voxels in the label clicked and display the result in the Cursor Information area in the Tools Window. This operation may take anywhere from 1 to 10 seconds depending on the size of the label clicked, so be aware that tkmedit may seem unresponsive for this length of time after setting the cursor with this option activated.
By clicking with button 2 with this tool, you can 'paint' a label in the segmentation. The color used can be set in the dialog box brought up by choosing Tools, Configure Segmentation Brush.... This tool is a brush tool, so it uses the global brush settings available in Tools, Configure Brush Shape... and in the Reconstruction Toolbar. Clicking with button 3 will 'erase' segmentation labels (by setting the label values to 0).
The painting function is similar to the Edit Voxels tool: the clicked voxel, and those around it depending on the brush radius, are set to the value specified in the Configure Segmentation Brush dialog. Clicking on a voxel with button 2 and the control and shift key held down will set the current painting color to the color of the clicked voxel. Edits can be undone with the Edit, Undo Last Edit menu item.
A flood fill is also available, activated by shift-clicking mouse button 2 or 3. This tool fills areas with values equal to or similar to the voxel clicked. It looks for contiguous areas in the source volume to fill in the segmentation with the selected color. It is configured in the Configure Segmentation Brush dialog. It has parameters for 3D, the source volume, fuzziness, distance.
Source Volume: Specifies which volume to use when looking for similar voxels, so that the Main, Aux, or segmentation volume can be used to look for regions. Fuzziness: Determines the level of similarity to consider when finding regions. If it is 0, only voxels with exactly the same value as the voxel clicked will be set. If it is greater than 0, this is the maximum value difference from the clicked voxel that a contiguous voxel can have to be considered in the same region. Distance: Determines the maximum size of the region to fill from the clicked voxel. If it is 0, there will be no distance limit. 3D: Determines if the fill is in-plane only or will fill in three dimensions.
A fill can be undone with the Edit, Undo Last Edit menu item.
To save changes to a segmentation, choose File, Save Segmentation to overwrite the original segmentation volume or File, Save Segmentation As... to specify a new directory in which to write the COR- volume.
Diffusion Tensor Images can be viewed as an overlay. The red, blue, and green colors represent the direction of the vectors.
DTI volume data sets consist of two volume: a three frame eigenvector volume (EV volume) and a fractional anisotropy volume (FA volume). These must be specified in the File, DTI, Load DTI Volumes... dialog box. There will be a considerable delay while loading DTI volumes as tkmedit does some pre-processing.
The eigenvector volume describes the directionality of diffusion in a particular direction (with the first EV being the direction of greatest mean diffusion within each voxel), and the FA volume describes how homogeneous the diffusion is in a particular direction (high values mean that diffusion is primarily occurring in a single direction- and FA is calculated from something like the variance of the three eigenvalues).
7.2 Display options
Head points are displayed in full color. The red, green, and blue spectrums represent the directionality of the EV volume. The opacity of the overlay can be configured in the dialog box brought up by choosing View, Configure..., DTI Display.... The overlay can be hidden by unchecking View, DTI Overlay.
8.0 Head points
Head points data represent the location sensors during an MEG/EEG scan.
Head points data consist of two files: a list of points and their labels, and a transform file. These must be specified in the File, Load Head Points... to load head points data.
8.2 Display options
Head points are displayed as green diamonds in the Display Window. They can be hidden by unchecking View, Head Points. You can select a head point by clicking near it. The selected head point is drawn in red and its label is shown in the Tools Window.
When you are viewing the maximum intensity projection (by checking View, Maximum Intensity Projection), you will see all the head points. Note that in this view you can select head points in all planes, not just the current one.
You can edit the label of the currently selected head point by choosing Tools, Head Points, Edit Current Head Point Label.... Enter the new name in the dialog box. You will need to click the point again in the Display Window to see the new name in the Tools Window.
You can also modify the registration transform. Use the Tools, Head Points, Register Head Points... command to bring up a dialog box containing arrow buttons. Use these buttons along with the associated parameters to move the head points. It is easiest if you do this in the maximum intensity projection view.
Save changes to the head points labels by choosing File, Save Head Points. Save changes to the registration transform by choosing File, Save Head Points Transform. Both commands overwrite the original files.