The multisubject control is a specialized tool for computing multisubject composite fMRI activation maps. It can be activate through the pxitclbrainregister and pxitcldualmultisubject applications – the later has two multisubject controls to enable easy group comparisons. The multisubject control interfaces extensively with the registration tools for computing registrations and performing image comparisons etc. The pxitclbrainregister and pxitcldualmultisubject applications are dual-viewer applications for, among other things, computing and testing registrations. The two viewers are labeled as the Reference viewer and the Transform viewer from the role they play during registrations. The reference image is taken from the Reference viewer whereas the transform image is taken from the Transform viewer. The multisubject control leverages both these viewers and the Registration tools (accessible under the Registration menu) for its operations.

The Data Tree tool is in some respects a more generalized and updated version of this control; however for computing fMRI composite activations using the MultiSubject tool is probably more convenient.

Setup File Format

At the heart of the multisubject control is it's setup file, which is stored with a ".msb" extension. While the setup file can be generated entirely using the graphical user interface, experienced users prefer using a text editor to edit this file directly.

A complete setup file for a group having 3 subjects and 2 tasks (or contrasts) is presented below. The text in typewriter-like font represents the setup file, whereas normal text represents comments.

Critical Note: There MUST be no spaces " " in any of the filenames in the setup file. This is generally a bad idea. Use underscores ("_") instead.

1. File Header

The first line of the setup file is its its header which must contain exactly the text below. Any variations to this will lead to the setup file being rejected by the application.

2. Task Definition

fMRI experiments consists of a variety of tasks/contrasts. For example, a hand motor experiment, could have tasks "left v rest" and "right v rest" respectively . The multisubject control can handle a large number of such tasks provided that they are stored in analyze-format images with filenames of the form:

Common_PrefixTask_SuffixCommon_Suffix

For example for the tasks above the three tasks could be called:

1. /data1/study/subject22_leftvrest_tmap.hdr
2. /data1/study/subject22_rightvrest_tmap.hdr

where the common prefix is "/data1/study/subject22_", the common suffix is "_tmap.hdr" and the task suffices are leftvrest, and rightvrest respectively. Such a set of tasks is presecribed in the setup file as follows: where after the word "Tasks" the number 2 signifies that there are two tasks, each of which is described with a descriptive "Task Name" and the all-important Task Suffix.

3. Individual Subject Data

Each subject is defined using upto eight pieces of information as listed below. All images must be in Analyze format (.hdr,.img pair). The setupfile stores the filenames of the images/transformations.

1. The 3D Anatomical Image – the filename of a 3D image of the whole brain.
2. The "2D" Conventional (Scout) Image – a filename of the conventional anatomical image – i.e. the anatomical image acquired with the same slice-specification as the underlying fMRI study. whole brain.
3. The Functional Image which is the filename for the first task – in this case the "Left vs Rest Hand Motor" task. The filename must be in the same format as that described in the Task Definition section above.
4. The Reference Transformation which maps the Reference/Template Brain to 3D Individual Anatomical Image. This is a non-linear registration that performs inter-brain warping.
5. The Internal Transformation which maps the 3D Individual Anatomical Image to the "2D" Conventional (Scout) Image. This is a rigid (linear) transformation which accounts for the differences in position and orientation between the two scans.
6. Optional: The Echoplanar Image – is either a spin echo-anatomical image which is perfectly registered with the fMRI time series, or one of the fMRI time-series images (or perhaps the mean or median T2* image).
7. Optional: The Distortion Transformation which maps the "2D" Conventional Scout Image to the Functional/Echoplanar Image. This aims to capture the distortion in the echoplanar acquisitions used for fMRI. (This is often left blank, especially if the software generating the statistical maps – the task files performs some alignment between the echoplanar and conventional images. Ideally, this should be a non-linear transformation which captures the distortion, although affine linear transformations are also often used here.
8. Optional: The Field Map image which is a direct measure of the distortion. This is currently not used directly, although it might be used in batch-distortion computation in the future.

Note: As shown in the example below, the appropriate line must still exist even if an optional field is blank. See for example all "Fieldmap Image:" lines below.

4. Reference and Output Images

The final section in the setup file defines the Reference/Template Brain and filenames for storing the composite anatomical/functional maps. All outputs are in the space of the reference image. The outputs are:

• Average Anatomical – if desired the program can compute the average anatomical image using the transformations and the individual 3D Anatomical images.
• Std Anatomical – the standard deviation of the anatomical images.
• Average Functional – the average functional map image filename for the first task.
• Std Functional – the standard deviation of the first task.
• Tscore Functional – a t-test of the first task against zero.
• Three lines marked Legacy which exist for compatibility with older versions of the multisubject control.

The filenames for the three task-dependent outputs (Average Functional, Std Functional, Tscore Functional) must be in the same format as that described in the Task Definition section above.

---

The Multisubject Tool Graphical User Interface

This control has three tabs: "Base", "Subjects" and "Results". The user defines the reference brain and the tasks in the "Base"-tab. Individual subject images/transformations can be accessed in the "Subjects"-tab. All composite result computation/display is performed using controls in the "Results"-tab.

The menubar contains facilities for loading/saving the setup file, loading all images, performing batch computations (best avoided, use the command line batch mode tools instead), and for interfacing to the Image Compare tool in the Registration/Overlay Control.

Important: Loading a setup file does not load the images into memory – this is to allow manipulation of the setup file without the memory/disk-access overhead involved in loading all the images for a large study. To load the images use the Load All Images menu option under the "Images" menu.

The Base Tab

This essentially consists of the Reference Image Control and the Task definition Control, both of which are described next.

The Reference Image Control

This is a common control in BioImage Suite for handling images. It consists of two textboxes, which display information about the current image and a set of buttons for manipulating the image (See Figure 3).

The three textboxes display (i) the filename, (ii) the dimensions – if these are "1 1 1" this means that the image is not in memory, just its filename, and (iii) a detailed description of the image.

The Load button is used to load the image into memory. The Save button can be used to save the image, perhaps in a different location. The Browse button is used to define the image filename without actually loading the image. The Display Ref and Display Trn buttons display the image in the reference and transform viewers respectively. Finally the Clear button unloads and clears the image.

The setup file must be saved for changes to the image filename to be made permanent.

The Task Definition Control

The task definition control enables the addition/removal and editing of tasks. This relates to the Task Definition section of the setup file described earlier. As shown in Figure 4, this control consists of a list of tasks (left) with two associated buttons for adding a new task and removing the selected task, and a task window right for editing the task description and task suffix for the current task. Edits are acted upon when the Update button is pressed.

You may not delete the task that is currently active – this is the first task when the setup file is loaded, as this makes the setup file invalid. The current task is selected in the Results tab, described below.

The Subject Tab

The subjects tab, shown in the middle of Figure 2, is where information for each subject can be manipulated. This relates directly to the Subject Definition section of the setup file described earlier. The graphical user interface for the Subject tab is divided into a left column which contains the list of subjects and two buttons for adding a new subject and removing the currently selected subject, and the right column which displays the information for the current subject. The currently selected subject is also used by the Overlay Controls in the Results Tab (below) to determin which subject's data to overlay when the user requests "Individual Subject" images.

The right column of the Surface Tab contains the subject properties. The properties frame has a textbox at the top which has the name of the current subject (extracted automatically from the Anatomical Image), and then below this a nested tab control with two panes, "Main"  and "Distrotion Correction". Between them, these two panes contain controls for manipulating the 8 elements of the individual subject definition described above.  

1. In the Main Tab
• Anatomical Image which stores the 3D Anatomical Image.
• Functional Image which stores the Functional Image for the current task.
• Transformation Anatomical --> Reference which stores the  Reference Transformation.
• Conventiona Image which stores the "2D" Conventional (Scout) Image.
• Transformation Conventional --> Anatomical which stores the Internal Transformation.
2. In the Distortion Correction Tab
   
• Spin-echo Echoplanar image which stores the Echoplanar image.
• Transformation Echoplanar --> Conventional which stores the  Distortion Transformation.
• Fieldmap Image which stores the Field Map.

Of these controls, 5 are image controls. These are similar to the reference image control shown in Figure 3. They are labeled as: The other 3 controls are transformation controls and are used to store the Reference, Internal and Distortion Transformations respectively.

One of these is shown in Figure 5. It consists of (much like the image control shown previously) of three textboxes and a set of buttons. The three textboxes display (i) the filename, (ii) the class of the transformation (vtkTransform=linear, vtkpxComboTransform=nonlinear), and (iii) details about the transformation. If the transformation is a linear one, then the 4x4 matrix is shown in the details box.

The Load button is used to load the transformation and similarly the Save button can be used to save the transformation, perhaps in a different location. The Invert button can be used to invert the transformation -- use with care in the case of nonlinear transformations, and the Clear button sets the transformation to identity.

The Check button can be used to confirm the quality of the transformation. It places the original reference image (e.g. in the case of the Anatomical->Reference transformation, this is the 3D Reference Image Template) in the left, or Reference Viewer, and places a resliced (warped) version of the Transform image (in this case the Anatomical image) in the Transform Viewer. The linked cursors of the two viewers can then be used to navigate to important structures and visually inspect the quality of the mapping.

The Go to Compute button sets the program for computing the transformation. It places the appropriate reference image in the Reference viewer, the appropriate Target in the Transform viewer and opens the Registration control at the appropriate tab (either linear or nonlinear). Next the user needs to click on a button in the Registration control (e.g. in the linear case either "Rigid" oir "Affine", in the non-linear case "Compute Linear + Non Linear Registration") to start the registration. Once this is completed it can be migrated back to the multisubject tool using the Grab button. Until the Grab button is pushed the computed transformation is not stored anywhere and could be lost if the program is closed.

All modifications to the Individual subject information are saved when the Setup File is saved. Use Setup/Save Setup File button in the multisubject control to do this. It is suggested that the setup file is saved periodically.

The Results Tab

A user, once she he has finished defining the input data is defined and the registrations check, most of the time (while using the Multisubject Control!) in the Results-tab. This is divided vertically into three large units, the Compute Output frame (shown in Figure 6), the Output Results frame (shown in Figure 7) and the Output Overlay pane (see Figure 8). Briefly, the Compute Output frame is used to select the current task and to compute average maps. The Output Results frame can be used to directly visualize these results as well as Load/Save them to disk. The Output Overlay frame has functionality for generating anatomical/functional overlays for visualization.

The Compute Output Frame

The Compute Output frame is shown in Figure 6. On the left hand side there is a frame titled "Current Active Task" which lets the user select the current task. The multisubject control only keeps one task in memory. To change the current task select it in the list and press the Change Current Task button. Pressing this will load the specific task files for all the subjects as well as the average, std and t-score functional maps for this task if they exist.

Composite functional maps, for the current task, are computed using the controls on the right hand side. The user may set the resolution at which these are computed (lower resolution=faster computation) as well as the interpolation mode for image reslicing. The Compute Average Functional button  the composite maps (i.e. average functional, std functional and tscore functional). These are automatically saved if the Autosave results checkbox is enabled. Alternatively if a user desires to warp all functional data to a common frame and process them using external software, he can use the Warp Tasks to Common Space button. Both these buttons will perform their respective operations for the current task. If multiple task computations or exporting is desired, it can be accomplished using similarly named options from the Batch menu, in the multisubject control menubar. Finally, tje Compute Average Image button computes the average anatomical image -- this is useful as a quick visual check on the  transformations.

The Output Results Frame

The Output Results frame, shown in Figure 7, consists of a single control, which is a multi-image control. This is a multiple image version of the standard image control used in the other tabs, e.g. see the description of the reference image control (see also hown in Figure 3). The only additional element is that a set of images share this control. The current image is selected from the list on the left hand side -- see Figure 7.

The Overlay Controls Frame

The overlay controls frame is a common control, also found in the Registration and DataTree tools, for creating overlays of functional data on anatomical data. The basic principle used for the overlay is that the users sets a threshold for what constitutes significant function using the Low Threshold slider and then saturates the functional data at the level set by the High Threshold slider. For more details see the description in the Registration tools page.

This overlay control has three additional options over the standard overlay control.

1. The Output Viewer can be used to direct the overlay to either the Reference or the Tranform Viewer.
2. The Base drop menu can be used to select which image will be used as the anatomical image on which the function is overlaid.
3. The Function drop menu is used to select which functional image will be used in the overlay.

If in either the Base or the Function drop menus an option marked "Individual" is selected, this refers to the individual anatomical/functional image from the current subject -- the subject that is selected in the Subject Tab.

---

About this manual.