QUENCH Tutorial

From VISTA LAB WIKI

Jump to: navigation, search

QUENCH is a tool for interacting with estimated fiber tracts. We often use QUENCH as a standalone application, although it can also be used in close coordination with mrDiffusion and ConTrack. This page explains the QUENCH interface in standalone mode. There is also a section below that indicates how to communicate between mrDiffusion and QUENCH.

To run this tutorial, you must:

  • Be able to launch, the executable QUENCH for your machine
  • Have the sample data set which can be downloaded either from
- The Vistadata repository, or
- The online data set

Contents

[edit] Overview

QUENCH starts as a blank slate. The first step in using QUENCH is to load a background image, which is called the Volume. Typically these are T1 or B0 anatomical images. These volumes are used to identify the relative location of the fiber tracts. You can load multiple volumes and choose amongst them during your work sessions.

We then load fiber tracts. The tracts can be visualized and edited inside of QUENCH.

We then load auxiliary data sets that enable us to color the fiber tracts with parameter values (e.g., fractional anisotropy, retinotopic position of the end points, and so forth).

We can save the working state and enable the user to quickly pick up an analysis where it was left off (load the current volumes, fibers, and labels).

You can create Volumes of Interest

There is a sample data set for following this tutorial.

[edit] Preparing volumes and fiber tracts

The T1 and B0 anatomical data are simply standard volumes stored as NIFTI files. There is nothing special about the QUENCH format for these data.

The fiber tracts are stored in a format called pdb (pathway database). This is the default format for ConTrack and was developed by the Camino team. We have written routines that convert between Matlab and the pdb format. These are used by mrDiffusion.

To read in pdb fibers you can use mtrImportFibers. Use dtiWriteFibersPdb to save a typical fiber group structure as a .pdb file.

The vistadata repository contains a T1 and B0 volume in the quench sub-directory. It also contains example fiber sets (fibers/LeftArcuate.pdb and fibers/RightArcuate.pdb). These are paths were generated and scored using the ConTrack set of algorithms. Each file contains the top-scoring 10000 fibers as estimated in a ConTrack analysis.

[edit] Loading and visualizing

Volume image (T1) in Quench
Arcuate estimates

Step 1: File | Load Volume
This brings up a navigation window where you can select the t1.nii.gz or bo.nii.gz file from the vistadata repository (quench subdirectory). You must load one volume at a time. Suppose you load the T1 data first, then you will see an image like the one at the right.

Step 2: File | Load Pathways
This brings up a navigation window which you can use to select the right and left arcuate files from the repository data set. Once these are loaded the image will look contain two colored groups of arcuate estimates. Notice that these estimates contain many fibers that are not likely to be part of the true arcuate. These files contain a lot (10K) of possible arcuate fibers. The highest scoring ones (say the top 500) are probably genuinely in the arcuate. As you relax the scoring criterion the chance of a false alarm increases.


Step 3: Saving and Loading State File (Optional)
File | Save State
File | Load State
The state file saves the "state" of a project so that you can keep working on it or load it at another time. Suppose you get called away but you want to save everything. Then select Save State. This will bring up a navigation pane that allows you to save the current state. When you return to work later, you can load the saved state. (We have seen bugs in this condition, though it often works. See BUG page to check status).

[edit] Changing Volumes - Backgrounds and Overlays

Background and Overlay Management

If you load more than one volume as a background, you can switch between the Volume you use in the background.

  • To change select Panels | Backgrounds and Overlays.

A window will popup that enables you to control different aspects of which Volume is rendered and how that Volume is rendered. Conceptually, the volume data can be present either as the fundamental background or as an overlay. While you would not ordinarily use a T1 and a B0 as a background and overlay, you might use a T1 and an FA as a background and overlay.

  • To decide whether the Volume is visible, select the checkbox (A) for that Volume.
  • Then to select which volume is the background, select one of the radio buttons (B).
  • You can also select a color map for the volume that is used either as the background or as the overlay (C). You choose the colormap by clicking on the colormap icon for that volume (C).

When you select a particular color map, you can further refine which part of the data are shown in the overlay by using the text boxes and sliders in the bottom part of the panel. These are marked Color Range and can be manipulated using the slider and a set of text boxes and radio buttons in the middle.

Here is what they do:

  • The slider in the middle of the panel (D) controls the range of values that are shown in the overlay. It has a simple graphical interaction that you will probably understand right away.
  • The slider at the bottom (E) governs the transparency of the overlay.
  • The textboxes at the left and right (F) set the range of overlay boxes that are shown.
  • The radio buttons (G) provide an alternative method for controlling the overlay values. The textbox (right of G) indicates the percentage in the middle refers to the top or bottom percentage. The gray button (H) at the right of the middle box turns off the function of the percentage box. To use the percentage box again select it and type in a number.

You can control the range fairly completely from the slider (D) alone - just pull the slider around to set the range or the position. The value of the text boxes is that they allow you to set the numbers precisely. We suggest that you get the slider positioned roughly as you like it, and then look at the various text boxes and the percentage box below.

[edit] Creating and Reading a volume of interest (VOI)

Not yet implemented.

[edit] Loading multiple fiber groups

QUENCH has the ability to load multiple fiber groups at once. Multiple fiber groups can be loaded at once or fiber groups can be appended to a session with previously loaded fibers. New fibers can also be loaded and overwrite the fibers currently in the session.

  • File | Load Pathways
- This will bring up a window allowing you to choose a .pdb file to load into QUENCH.
- Note that you can hold down CTRL to select multiple files to load.
- Each new fiber group that is loaded will be placed within a new "bin" in QUENCH.
- If you already have fibers loaded in QUENCH you will be asked if you would like to Append or Overwrite the current fibers.

[edit] Pathway Editing

Unique to QUENCH is the ability to use dynamic gestures to edit pathways. This allows the user to manually remove pathways from a given fiber group that are the result of data artifacts or are not biologically plausible. Pathways can also be removed to allow visualization of a smaller subset of pathways within a given fiber group. Pathways within a given group can also be segmented into different groups and saved out as separate files - thus allowing the user to analyze different groups of fibers individually.

Pathways generated with ConTrack and scored with the ConTrack scoring algorithm can further refine their pathway selections dynamically using the built-in fiber group filters - accessible through Panels | Refine Selection.

== Manual Selection ==
Mode selection toolbar
Quench pathway selection using Touch and Remove modes.

Edits to pathways can be made using dynamic gestures. Mark and selection modes can be selected by clicking the desired mode within the Mode selection toolbar (see image) in the main QUENCH window.

Note that selection modes will work between bins only when fiber group assignments are not locked. Edit | Lock Assigned Groups

  • Mark Modes:
- Touch: Allows the users to effectively "touch" the pathways that will be involved in the operation. An example of this is shown in the image at right. Holding down CTRL when this mode is selected turns the cursor into a selection tool which is active when the user clicks the left mouse button.
- Surface Allows the user to "circle" pathway points within a single plane for inclusion in a given operation. Holding down CTRL when this mode is selected allows the user to circle those points (on a single plane) to be included in a given operation. Note that when this mode is selected whichever view is currently highlighted will be the view used with this mode. The user can change the view by typing C for coronal, A for axial, or S for sagital.
  • Selection Modes:
- Add - This mode will add the pathways you touch to whichever bin is selected.
- Remove - This mode will remove the pathways you touch into the trash bin. Those fibers can be viewed only if the trash icon is clicked.
- Intersect - This mode will retain (in the selected bin) only those fibers you touch. The fibers from that group that are not touched will be added to the trash. This operation can only be performed on fibers that are in the current bin.
  • To execute a given gesture:
- Hold down CTRL and click with the LEFT MOUSE BUTTON to "TOUCH" the pathways you wish to be involved in the operation (see image at right)
- You'll notice that a red line will appear tracing the path of your gesture and effectively highlighting which pathways will be involved in the operation.

[edit] Statistical Selection

Selection Refinement Window - Stats Filters

This type of pathway editing can only be done with those fibers that have "statistics" in the .pdb file structure. Typically these fibers have been tracked and scored with ConTrack. Although Matlab functions do exist that allow the user to add statistics to a given fiber group. For more on this see the section on relevant Matlab routines on the main QUENCH page.

Pathway selections can be automatically (and dynamically) filtered using the statistics contained in the .pdb file. The statistic filter window can be accessed via Panels | Refine Selection. The image at right shows the typical Stats Filter Window that comes up when you are working with fibers generated and scored using ConTrack. Values at the left and right of the blue slider (A) reflect the numerical range for that parameter.

  • Filtering pathways based on fiber statistics (When the panel first appears, all the text may not be visible. Normally, you can resize the panel to make the text easily visible.)
1. Choose the fiber group you wish to filter by clicking the corresponding bin number in the main QUENCH window.
2. Click -> Panels | Refine Selection -> Choose the Stats tab
You will then see a window like the one at right.
3. Choose your statistical filter thresholds for the desired statistic by:
a. Clicking and dragging the endpoints of the blue slider (A)
b. Entering the lower and/or upper thresholds numerically in the text boxes (B) under the slider.
c. Entering a percentage threshold. This is done by choosing the top n% or bottom n% by clicking either the top or bottom blue radial button (C) next to the % text box (D) and entering a number in that text box (D).
  • Filter | Stats | Tips:
  • Clicking the "X" (E) at the right of the central text box will cancel all thresholds for that parameter.
  • The top panel (F) shows the name of the fiber group the filter is working on as well as the number of pathways remaining in each bin. You can also choose to lock or unlock the assignments within this panel.
  • While the Selection Refinement Window is open you can highlight another bin to place the filtered pathways into that bin instead of the trash.
  • Only fibers in the selected bin will be filtered, so be sure to have the correct bin selected.
  • Pathways are filtered dynamically - pathways are updated instantly in the main QUENCH window based on the filter thresholds.

[edit] Panels | Per point color

Per point color window

Pathways can be colored, using a user-designated colormap, based on a given statistic.
To color pathways using a given statistical parameter:

  1. Load the fiber group you wish to color per point - be sure that the group has per point statistics within the .pdb file.
  2. Clicking Panels | Per point color will bring up the window shown at right.
  3. Select the statistic you want to use to color the fibers in the dropdown menu (A)
  4. Select the colormap by clicking the icon (B)
  5. Set the thresholds by:
    I. Clicking and dragging the endpoints of the blue slider (C)
    II. Entering the lower and/or upper thresholds numerically in the text boxes (D) under the slider.
    III. Entering a percentage threshold. This is done by choosing the top n% or bottom n% by clicking either the top or bottom blue radial button (E) next to the % text box (F) and entering a number in that text box.
  • See the image in the next section for an example image.

[edit] Panels | Screenshot

Image Preview Window - Showing per point color of arucate length.

Screenshots can be created from within QUENCH. The advantage of this method is that the quality of the screenshot can be controlled and high-quality renderings of fiber groups are possible.

To create a high-quality screenshot in QUENCH:

  1. Click Panels | Screenshot - the window at right will appear.
  2. Drag the slider at the bottom of the window to choose the quality of the screenshot.
  3. Click Refresh to see a preview of the image.
  4. Click Save and choose a file location.
  • The refresh process can be slow and depends on your system speed.

[edit] Saving Fibers and Working State

Saving Fibers
After you have made edits to your fibers you can choose to save them for later analysis. To do this:

  • Click File | Save Visible Pathways (as PDB) and choose a file name and location.
- Note that this will save all of the fibers that are visible in the active QUENCH window into the same PDB file.

Saving Working State
When working on a project it is helpful to be able to return to a working state. This is particularly useful during large involved segmentation projects. Saving the working state file (.qst file) is simple:

  • Click File | Save State and choose a file name and location.
- Note that a temporary .qst file is automatically saved for you when you open QUENCH. This file is saved continusouly while you work - in case of a crash you can load this file. By default it is saved in the working directory, from which you called QUENCH. The default file name is ~lastState.qst.
- Loading a state file will load the bin assignments as well as the background volumes that were loaded when the state was last saved.

[edit] Matlab routines and Quench

The following sections use describe routines written in matlab that operate on fiber groups and state files that can be loaded in Quench.

[edit] Saving Statistics to an Existing Fiber Group

White matter probability statistic shown across a group of corpus callosum fibers.

If you have a file containing a fiber group this section will explain how you can add statistics to that fiber group structure in matlab and display those statistics per point, or use that information to refine your fiber group selection in QUENCH.

To save stats to an existing fiber group we will use the following function: dtiCreateQuenchStats This function adds statistic information to a fiber group. The statistic can be geometry based (eg. Length) or image/array based (eg. FA map).

In the following example we will use the white matter probability image (wmProb.nii.gz) and add that statistic to a group of fibers found within the mrDiffuison sample data set.

    1. Load the fibers in Matlab. fg = mtrImporFibers('pathToYourSampleData/mrDiffusion/dti40/fibers/CCFG.pdb');
    This will load the fiber group structure into matlab's memory. Which will look like this:
    fg = name: 'CCFG' colorRgb: [200 200 100] thickness: -0.5000 visible: 1 seeds: [] seedRadius: 0 seedVoxelOffsets: [] params: {} fibers: {3122x1 cell} query_id: -1 pathwayInfo: [1x3122 struct] 2. Read in the image with the stats you want in the fiber group. wmProb_img = readFileNifti('pathToYourSampleData/mrDiffusion/dti40/bin/wmProb.nii.gz');
    This will load the image into matlab's memory.
    3. Add the stats info to the fiber group structure. newFg = dtiCreateQuenchStats(fg,'WMProb_avg','WMPROB', 1, wmProb_img, 'avg');
    For a summary of how the above function works see the help file within Matlab.
    4. Save the new fiber group structure. mtrExportFibers(newFg,'stats_CCFG.pdb');
    This will save the fiber group with the name 'stats_CCFG.pdb' in your current directory. You can then open those fibers in QUENCH. If you view them in per point color, using a jet color map, you should see the image at right.

[edit] Transferring fibers from mrDiffusion

Occasionally you may want to load fibers into QUENCH directly from mrDiffusion.
This can be done from within mrDiffusion.

  1. Generate the fiber group in mrDiffusion.
  2. Remove from the mrDiffusion GUI all fiber groups except the ones that you wish to load in QUENCH.
  3. Use the pulldown: "View | QUENCH | Push current paths". You will be queried whether you want to over-write the current QUENCH paths. Say yes. The QUENCH screen should then load the fibers.

To load the fibers back into mrDiffusion after you finish your work in QUENCH:

  1. Remove all fiber groups from mrDiffusion
  2. Use the pulldown: "View | QUENCH | get current paths" to move the edited groups from QUENCH into mrDiffusion.
    The distinct groups you created in QUENCH will have the same colors and numbers in mrDiffusion.

[edit] Writing a state 'qst' file from a fiber group

 % 
 %   quenchWriteStateFromFiberGroup([fg],[t1File],[outName])
 % 
 % OVERVIEW: Takes a mrDiffusion fiber group and associated t1File and
 %           creates a Quench '.qst' state file using the fg.subgroup field
 %           to identify different group assignments in Quench.
 % 
 % NOTE:
 %           This function saves an accompanying pathway database file
 %           (.pdb) that will be loaded in quench when the state file is
 %           loaded. The T1 file can be stored anywhere as the full path is
 %           written to the sate file - the pdb file and the qst files are
 %           saved, and should be stored, in the same directory. 
 % 
 % INPUTS:
 %       fg      -  a mrDiffusion fiber structure: can be a filename (.mat)
 %                  with a subgroup field wherein each distinct fiber is
 %                  given an idex unique to the fibergroup it belongs to.
 %                  The field fg.subgroupNames should have the names for
 %                  each of the unique fiber groups indexed. 
 %       
 %       t1File  -  full path to t1 file. Important: Do not use symbolic
 %                  links. If you use a symbolic link in linux then we can
 %                  resovle the link, but in windows or MAC you're on your
 %                  own.
 %       
 %       outName -  the stem for the qst and pdb filenames. If not provided
 %                  the name will be taken from fg.name.
 % 
 % WEB RESOURCES:
 %       mrvBrowseSVN('quenchWriteStateFromFiberGroup');
 % 
 % 
 % EXAMPLE USAGE:
 % 
 %   Default usage: Provide path to fiber group and t1 file - take name
 %                  from fiber group.
 %       >> fg = 'MoriGroups.mat';
 %       >> t1File = '/some/Path/t1File.nii.gz';
 %       >> quenchWriteStateFromFiberGroup(fg,t1File,[]);
 % 
 % (C) Stanford University, VISTA Lab 2012

[edit] Writing fiber groups from a state 'qst' file

 % 
 % quenchWriteFibersFromState([stateFile],[fg],[fgBins],[outName],[outType='pdb'])
 % 
 % OVERVIEW: Take a quench state file and from that file read the unique
 %           subgroup indices and save out a fiber group (pdb) for each 
 %           unique value. 
 % 
 % NOTE:
 %           This function will be parsing out a text file. If the text file
 %           has been altered in any way this will fail spectacularly. 
 % 
 % INPUTS:
 %       stateFile - a Quench stateFile. -- if there is one qst file in the
 %                   directory where this function is called then it
 %                   will be selected and used. If there are multiple then
 %                   it will prompt the user if it's not provided.
 % 
 %       fg        - a pbd fiber group associated with the qst file. This
 %                   will be read in from the qst file. If the fg is not
 %                   within the same directory then the user will be
 %                   prompted if not provided.
 %       
 %       fgbins    - The bins in the qst for each of the fiber groups user
 %                   wants pulled out of the state file. Defaults to all.
 %       
 %       outName   - A [numel(fgBins) X 1] cell array containing the pdb 
 %                   filenames. If not provided the names will be taken from
 %                   the qst file by default. 
 % 
 %       outType   - Type of file to save out: 'pdb' or 'mat' 
 % 
 % WEB RESOURCES:
 %       mrvBrowseSVN('quenchWriteFibersFromState');
 % 
 % 
 % EXAMPLE USAGE:
 % 
 %   1. Default usage where the '.qst' and '.pdb' file are in the same
 %      directory and only one '.qst' file exists.
 %       >> quenchWriteFibersFromState;
 % 
 %   2. Same as 1 above, but return only bins 1 4 8 from the 'qst' file and
 %      retain the names used within the 'qst' file:
 %       >> quenchWriteFibersFromState([],[],[1 4 8],[],[]);
 % 
 %   3. Same as 2, but give each group a specific name:
 %       >> quenchWriteFibersFromState([],[],[1 4 8],{'fg_1','fg_2','fg_3'},[]);
 % 
 %   4. Provide all inputs:
 %       >> sateFile = 'greatFileName.qst';
 %       >> fg = 'greatFileName.pdb';
 %       >> fgBins = [1 12 29];
 %       >> outName = {'fg_1','fg_2','fg_3');
 %       >> outType = 'pdb';
 %       >> quenchWriteFibersFromState(stateFile,fg,fgBins,outName,outType);
 % 
 % 
 % (C) Stanford VISTA, 2012 [lmp]
 %

[edit] Integration with fMRI data

Not yet implemented.

(But see our work on visual field maps and white matter pathways).

[edit] Additional Resources

The gesture interface portion of QUENCH was derived from a previous software project by Dave Akers, CINCH. See the CINCH paper website for descriptions of the original version of the gesture interface, and a short movie showing examples of its use. Here is a link to using CINCH for performing corpus callosum parcellations. It provides some techniques for using CINCH to segment many fibers out of one large group. [1]

Personal tools