Skip to content


Personal tools
You are here: Home » AFNI » Documentation » Misc Items » Creating Regions of Interest (ROI) in AFNI

Creating Regions of Interest (ROI) in AFNI

Document Actions

Timothy Souza 11/20/99

STEP1: Creating a mask dataset

STEP2: Basic ROI drawing technique

STEP3: AFNI set-up to draw ROIs

STEP4: Making corrections to ROIs

ROI analyses:
- Counting active voxels per ROI
- Percent change per ROI
- Extracting timeseries info per ROI

Creating a mask dataset

- ROIs in AFNI must be drawn on what is called a "mask dataset".  A mask dataset is basically a functional dataset in which all values of the dataset are initally set to zero. "Drawing" an ROI on the mask dataset changes the functional value of an area of the mask dataset, to a whole number value other than zero. Each ROI drawn on the mask dataset may be given a different value, allowing discretion between different ROIs. 
 -The mask dataset is created as a functional overlay (fim), which is placed over the bold dataset in order to perform various ROI analyses. The ROIs that have been drawn on this dataset, therefore, act as a mask by grouping the functional voxels below them as an "ROI".  Also, because the rest of the mask dataset carries a value of  zero, only those areas that have been given a new value by drawing operations are considered ROIs. 

1. Click on "define datamode" -> "plugins" -> "dataset copy 

2. Choose the BOLD dataset as input, for output prefix, name such as "subj"_master_ROI".  This mask dataset you are about to create can contain all of the ROIs you wish to draw.  Choosing the bold dataset as input allows the mask to have the same geometrical dimensions as the bold dataset. 

3. data fill: choose zero (one), this makes a new dataset with one sub-brick, and fills the entire dataset with a value of zero, which is the base for creating your mask. 

4. type: choose FIM .... (functional intensity map), this will allow the ROI mask to be overlayed onto the anatomical dataset 

Basic Technique for Drawing the ROIs 

    5. "switch anatomy" to the BOLD dataset...."switch function" to the new mask dataset that you just 
        created.  Now the mask (FIM) dataset is overlayed over the BOLD dataset, so you will actually 
        be drawing on the mask, while it will appear that you are drawing on the BOLD directly. 

    6. to begin drawing the ROI, "define datamode" -> "plug-ins" -> "draw dataset".  Now you can draw 
        the actual ROI on the mask. 

    7. In the (AFNI Editor) "draw dataset" window, choose your mask dataset. 
        drawing value:  (any value that is nonzero will work, remember that the entire mask background 
                                 is zero) Use a different value for each ROI that is drawn.  Since this value is an 
                                 intensity, it will be represented, or assigned a color of your choice, in the intensity 

        drawing color:  any color, default is yellow. This is not very important. The "drawing color" is 
                                 the actual color displayed during the act of drawing.  The final overlay color of 
                                 each ROI is defined by the intensity colorbar settings and can be easily changed. 
        drawing mode: 1) select "closed curve" to draw the outline of the ROI on each appropriate slice 
                                 of the bold, using the middle button on the mouse. Make certain to close the 
                                 outline of each ROI. If you prefer, select "points" as the drawing mode, and be 
                                 sure to close the outline. 
                                 2) After drawing the outline, change the drawing mode to "flood value" and 
                                 middle-click on the inside of each ROI on each slice. (see figure below) 
                                 3) If satisfied with your ROI, hit save
                                 Remember that only the previous drawing operation can be undone using the 
                                "undo" button. (see "making corrections to the ROI mask") 
                                 - Choosing a different drawing value for each ROI is what enables you to draw all 
                                 of the ROI's on one mask, and most importantly, will allow you to identify each 
                                 ROI later on.  As shown in the example below, the left insula is drawn with a 
                                 drawing value of 2. 

- Each ROI is a solid color, and each ROI is now represented by a drawing value, which is contrasted from the rest of the mask, which still has a dataset value of zero.  Remember to choose a different drawing value for each ROI you plan to draw !
Suggested Setup for Drawing the ROIs  

- Although the ROIs here will be drawn over the BOLD dataset, it is best to set up the AFNI controller windows so that you can view the real-time results of your  ROI drawing projected over the MPrage. The latest versions of AFNI make this possible by allowing you to spawn a second controller window and image window, by clicking on the "new" button in the main AFNI controller window. 
(Note: While it is possible to draw ROIs in AFNI directly on a mask dataset of the MPrage, it requires drawing on many slices, and the final ROI may be inaccurate in relation to the BOLD. This may be due to warping, and also because of inaccuracies which arise when changing the resolution of the mask (drawn at MPrage resolution) to conform to the BOLD resolution . 

- Below is a suggested AFNI window setup for drawing ROIs 

- AFNI window [A] is set to the MPrage as anatomy, with the mask dataset (hereVMo_master_ROI+orig) as the functional 

- AFNI window [B] is set to the BOLD dataset as anatomy, with the mask dataset (again, here VMo_master ROI+orig) as the functional. 
   The AFNI window which displays the BOLD dataset  (here it is [B]), is where you will actually draw the ROI

- However, with this setup, which also has a second controller window displaying the MPrage (and most importantly, the mask dataset VMo_master_ROI as the functional overlay), you will be able to check the anatomical position of each ROI as you draw it. 

- Again, for the sake of efficiency and convenience, I have placed the respective "see function" controller window next to each image window.  Also, because each ROI will have a discrete integer value, it is possible to set the intensity colorbar accordingly. 

- The last window you will need to position is the "AFNI Editor" window with your drawing settings. This is spawned by "draw dataset". 

Making corrections to the ROI mask 
  There are two basic methods for correcting a poorly drawn ROI or removing it altogether: 

  method 1: Using a drawing value of zero 
   - Draw on the mask over the region to be corrected, using a value of "0" in the "AFNI editor". 
  This is basically done the same way an ROI is drawn, except that the drawing value is zero.  The area 
  of the mask you are drawing over will be changed back to a functional value of zero.  Since no 
  functional color value is displayed for zero, this effectively erases poorly drawn ROIs, or can be used 
  to edit a portion of a particular ROI. 

 method 2: Deleting poorly drawn ROIs from the mask (3dmerge) 
  - The AFNI command line program 3dmerge can be used to edit out an ROI completely from an ROI 
  mask.  Since the ROI mask is a functional dataset containing intensity values (one for each ROI), a 
  particular ROI can be removed from the dataset by "clipping out" its functional value with 3dmerge. 
  This removes the entire ROI from the mask, over all slices.  This method requires that the output 
  (clipped) mask dataset be given a new name. 

  general format: 
  3dmerge -2uclip <lower limit value> <upper limit value> -prefix <mask output name> <mask input name>  

  ex: To remove an ROI which is represented by a functional mask value of 3, the 3dmerge command 
  would be similar to: 
  3dmerge -2uclip 2  4 -prefix VMo_masterROI2 VMo_masterROI+orig.BRIK 

  This effectively clips out the functional value of 3 (represented by values 2 and 4) and renames the 
  input ROI mask VMo_masterROI+orig.BRIK to VMo_masterROI2+orig.BRIK

Counting active voxels per ROI (3dmaskave)  
 - Once the ROIs are drawn, it is possible to perform active voxel counts per ROI, at a particular 
  r-value threshold, for each particular condition, using the AFNI command line program 3dmaskave. 
  3dmaskave can have many uses in extracting data from ROIs, based on how the command line is set 
  up. (see 3dmaskave -help documentation).  Like most other AFNI command line programs, 
  3dmaskave has the benefit of being scriptable, and its output may be redirected to a text file. 

  general format: 
  3dmaskave -mask <mask input name> -mrange <ROI mask value> <ROI mask value>  -dindex 1 
 -drange <r thresh> 1 <fico name>  (>> redirection filename option) 

  - For example, suppose there was an ROI with a mask value of 7, in a mask file named 
   VMo_masterROI+orig. This mask will be used over a fico (VMo@1+orig) calculated from the 
   BOLD dataset for a particular condition. Since an active voxel count is needed, we will apply an 
   r value threshold to this fico (here it is 0.3500 to 1). The correlation data is subbrick 1 of the fico 
   (dindex 1). The output will be redirected to a text file named VMo_voxcount. 
   The 3dmaskave command line would be: 
  3dmaskave -mask VMo_masterROI+orig.BRIK -mrange 7 7 -dindex 1 -drange 0.3500 1 VMo@1+orig.BRIK >> 

  - To get the total number of voxels in this ROI, leave the r value threshold out of the command line, 
   therefore including all voxels in the output: 

   3dmaskave -mask VMo_masterROI+orig.BRIK -mrange 7 7 -dindex 1 VMo@1+orig.BRIK >> VMo_voxcount 

  - Again, in order to make a final output file that is useful, and easy to import into a spreadsheet 
    program, some scripting will be necessary. 

 Percent change per ROI  
 - Applying an ROI mask dataset to an fbuc (functional bucket) dataset, will allow other types of ROI 
 analysis.  Although the fico datasets typically carry two values per voxel (subbrick #0 "fit coef" or 
 intensity, and subbrick #1 "correlation"), an fbuc dataset can carry many more values per voxel. 
 A typical fbuc can contain as many as 6 or 7 subbricks (or more), in other words, each voxel in the dataset 
 carries 6 or 7 "types" of values.  An [fbuc6] may contain the following subbriks, depending on which 
 ones are chosen to include: 

 #0 fit coef 
 #1 % change 
 #2 % from average 
 #3 baseline 
 #4 average 
 #5 correlation 

 - For any desired measurement, the burden is on the user to decide how to best extract the information 
  out of the dataset, through the use of the ROI mask.  The average percent change per ROI can be 
  calculated through the use of an fbuc for each condition, 3dmaskave, and the ROI mask. 
 - There are many variations on the syntax of this command line, based on the type of information the 
  user wishes to extract from the ROI.  For example, the user may wish to extract mean percent change 
  for the entire drawn ROI, or for just a particular subset of voxels within the ROI (i.e. all voxels above 
  a particular threshold). 

  Below is an example of how to derive the mean percent change per ROI, for a particular condition, 
  based on the active voxels of that condition, at a particular %change threshold level. 

  general format: 
  3dmaskave -mask <mask name> -mrange <lowROI limit> <high ROI limit> -dindex <subbrick> 
      -drange <inclusion range for pchange> -sigma -dump -indump <fbuc> (>> optional redirect to text file) 

  3dmaskave -mask ROI_mask -mrange 4 4 -dindex 1 -drange 0 10 -sigma -dump -indump condition1_fbuc@1 

- The command line outputs the mean percent change of all voxels within the ROI mask ("ROI_mask") 
 which have a mask value of 4 (i.e an ROI with a value of 4).  The criteria are that the voxels chosen must 
 have a percent change value in the range of 0 to 10 % change (user defined). The data index (-dindex) is 1, 
 which is the subbrik that contains percent change values.  The functional bucket (fbuc) is condition1_fbuc@1. 
- Options include: "-sigma" which outputs the standard deviation of % change, "-dump" prints out all of the percent 
 change voxel values which go into the mean, and "-indump" which prints out the i,j,k indexes of the voxels which 
 are included. In the example above, the output is redirected to a text file "condition1_text".  A more useful final 
 output file can be created through shell scripting.

 Extracting timeseries info from an ROI  
  - The MR signal level per timepoint can be extracted for each voxel within an ROI and output to an ascii file, using 
   the command-line program 3dmaskdump.    
  general format: 
   3dmaskdump -mask  <mask name> -mrange <lowROI limit> <high ROI limit> <3d+time brik>  (>> optional 
   redirect to text file) 

   3dmaskdump -mask ROI_mask -mrange 4 4 dataset1 >> text_file 

  - The command line above assumes that the the MR signal for the voxels in 3d+t "dataset1", which are defined 
   within ROI #4 in the mask dataset "ROI_mask", will be dumped out to either the screen, or a text file (if you choose 
   to use the file redirection option).  The resultng file or output will contain a column with the MR signal for each 
   timepoint, with a row for each voxel.  The i,j,k index numbers for each voxel will appear at the beginning of each 
   row, unless the option "-noijk" is inserted in the command line.

disclaimer:  Rights, ownership, and copyright of the AFNI software package belong to the Medical College of Wisconsin (MCW), and to the author of the software (Robert W. Cox).  The purpose of this page is to serve as an in-house reference for a type of analysis that we perform using the AFNI software package, and the methodology involved.  No claims are made as to the validity of these methods.

 • AFNI home page 
 Donoghue & Sanes Lab at Brown University 
 fMRI at Brown University 
  Brown University Department of Neuroscience 
  The Brain Sciences Program at Brown 

                  Last Updated : May 2000
Created by Alex Clark
Last modified 2005-08-11 01:37

Powered by Plone

This site conforms to the following standards: