html manual :: roi basics
This chapter aims to explain the basics of using froi for the analysis of functional data in association with FS-FAST. To begin, however, we need to speak the same language.
a note on terminology
As with any new software package, there is some new terminology to be learned. froi is no different. Let me explain some of the terms and abbreviations you will see throughout this manual:
- analysis -- name of an FS-FAST analysis that has been run through at least the selxavg-sess step.
- contrast -- name of an FS-FAST contrast that has been run through at least the stxgrinder-sess step
- roianalysis -- an FS-FAST analysis that was used to create an ROI
- func_path -- path to your functional data. In FS-FAST parlance, this would default to /session_directory/session_id/bold.
- roi_path -- path to your ROIs. By default, this is /session_directory/session_id/bold/roianalysis_ROI. The addition of the ROI suffix is to easily differentiate the directory in which your ROIs are stored from the original FS-FAST analysis.
- label_path -- path to your labels created by make_label or roi2label. This path is by default /session_directory/session_id/bold/roianalysis_ROI/label.
creating an roi
To create an ROI, use the make_roi program. Complete documentation for this program is presented in the Appendix; I will outline a few specific cases here.
make_roi requires five parameters and accepts many more; in most cases, you will give it more than the five required parameters. The necessary parameters are:
- -analysis analysis_name :: This is the name of a FS-FAST analysis created after mkanalysis-sess has been run.
- -contrast contrast_name :: The name of the contrast to use to create the ROI. These contrast maps are created after you have run stxgrinder-sess.
- -roi roi_name :: The name you wish to give this ROI. See the section below for suggestions on how to name your ROIs.
- -sf sessid_file :: The session ID filename.
- -df sessdir_file :: The session directory filename.
These five parameters will create a ROI that threshold your statistical map at a significance value of 10-2. Sometimes, however, you are interested in taking a higher threshold or using a different statistical map. In those cases, you can give one or more of the next three parameters:
- -map <t | sig> :: The statistical map to use to create the ROI. The default FS-FASt stat maps are a t-map and a sig-map. make_roi defaults to using the sig map.
- -threshold value :: Value to use for the threshold.
- -unsigned :: This parameter will consider your statistical map to be unsigned. Thus, if you give a threshold for a t-map of 2, all voxels with a t value greater than 2 or less than -2 will be selected for the ROI.
As an alternative to thresholding the t or sig map, I have implemented thresholding by false discovery rate (FDR). ** insert ref and brief explanation of FDR **
To use the FDR method, you can give one or both of the following parameters:
- -fdr value :: False discovery rate to use. Usually a FDR of 0.05 will give a reasonable ROI; see the references for some emperical studies.
- -np :: This parameter indicates that you wish to use the non-parametric calculations when using FDR. See the references for more details on when you might want to use this.
There are a few other parameters that can be given to make_roi that allow you to store data in non-standard locations; only use these parameters if you know what you are doing; as well, these parameters have not been extensively tested.
a note on logical roi naming
The method described above will create an ROI that is a simple threshold of your contrast map. Many times this will include more voxels than you actually want in your ROI. Since it is impossible for the computer to know which areas you want included in your final ROI, you will need to select a subset of the voxels that are included in this initial ROI. Thus make_roi immediately starts edit_roi, which allows you to edit this over-broad ROI.
When naming your initial ROI, its useful to name it based on the statistical map and threshold you are using. If you are thresholding a t map with values above 4, name your ROI (using the -roi parameter) as tover4. If you are using an FDR of 0.05, name your ROI fdr005. Of course these are just guidelines, but it will help simplify things down the road.
editing an roi
Following the creation of an ROI, make_roi immediately starts edit_roi, which can also be ran on its own from the command line. To use, edit_roi requires four parameters:
- -analysis :: Name of the analysis used to create the ROI.
- -roi :: Name of the ROI
- -sf sessid :: Name of the session ID file.
- -df sessdir :: Name of the session directory file.
edit_roi begins with all voxels in the loaded ROI being selected (Figure 1). Selected voxels of the current ROI are shown in red, while unselected voxels of the current ROI are shown in yellow. To clear all the voxels, press c; to select all voxels, press a. There are three modes in edit_roi; to change your mode, press m:
- None; do nothing
- Select: select voxels
- Select/Deselect; select a voxel if it is not selected, deselect a voxel if it is selected.
As well, there are a number of different brush sizes you can use, all the way from 1x1 voxels up through 11x11 voxels. To change the brush size, press b repeatedly until you select your desired brush size.
To simply the creation of ROIs, you can use the brush tool to select relatively large regions of cortex and then compute the intersection of those regions with the underlying map. Thus, you do not have to be unnecessarily careful when selecting your ROI; simply type i to compute the intersection (Figure 2).
To save your ROI, type s; the default save location is in the directory func_dir/analysis_ROI. Note that there is no need to add an extension for the filename; extensions are added automatically. For detailed information about the ROI format, please see the appendix.
Pressing q will quit edit_roi and warn you if you have not saved your ROI.
computing the roi average
Once your ROI is defined, it is time to compute the average response over all the voxels in the ROI. The program that performs this computation is compute_roi. This program works for both event-related and blocked data, as well as for gamma fitted and finite impulse response (FIR) analyses.
compute_roi has similar syntax to both make_roi and edit_roi. There can be confusion in the terminology, so read the following descriptions of the parameters carefully:
- -analysis analysis_name ::
Name of the analysis you wish to use for the ROI computation. You can use one ROI for multiple analyses; in fact, this is one of the strengths of the ROI approach. Of course the usual caveats apply, in that you must have the same slice prescription for all analyses that use the same ROI.
Thus if you wanted to compute the ROI average over the voxels in the face-event analysis, you would use -analysis face-event for this parameter.
- -roianalysis roianalysis_name ::
Name of the analysis under which you created your ROI. Note the difference between this parameter and the previous one. This corresponds to the name of the analysis used for your localizer runs, perhaps face-blocked. For different ROI computations across different analyses but using the same ROI, you would use the same roianalysis name.
- -roi roi_name :: The name of the ROI to use in the computations.
- -sf sessid :: The name of the session ID file.
- -df sessdir :: The name of the session directory file.
compute_roi will produce different results based on the nature of your analysis. For example, if you have a blocked analysis, you will get the average raw time-course for your ROI in addition to amplitudes for each condition (gammafit analyses) or time-courses (event-related analyses). Note that the raw time-course is just that, raw without detrending or noise reduction. For an event-related analysis you will not get the raw time-course (which would be meaningless), but you will get the same results as for blocked data. compute_roi is not designed to work with the abblocked or retinotopy analyses.
All of the results of compute_roi are saved in a Matlab structure for easy access. Included in this structure is the results of the ROI computation, information regarding the analysis, the ROI, the number of voxels in the ROI, etc. This structure can be accessed directly in order to view the results of the computation. If you prefer, however, you can use view_roi_results (see next section) to see the results.
There are a few other parameters (many of them similar to make_roi and edit_roi) that can be passed to compute_roi. A useful one is -text; this will output the results of the ROI computation as text files for easy importation into other programs, such as Excel or SPSS.
For more information, see the compute_roi manual page either in the Appendix or by typing compute_roi -man.
viewing your roi results
Now that your ROI has been created and the ROI averages have been computed, you probably want to see the results. The most direct way to do that is through the view_roi_results program (Figure 3). This will load the results of compute_roi and make them accessible through a Matlab graphical user interface (GUI). You will be able to view the mean response with or without standard deviation or standard error, along with percent signal change with or without standard deviation or standard error (Figure 4). If your analysis was blocked, you will also be able to see the raw time-course for each run.
The parameters for view_roi_results are similar to previous programs and are probably familiar by now:
- -analysis analysis_name
Name of the analysis you wish to use for the ROI computation.
- -roianalysis roianalysis_name
Name of the analysis under which you created your ROI.
- -roi roi_name
The name of your ROI.
- -sf sessid
The name of the session ID file.
- -df sessdir
The name of the session directory file.
Note that you can load other compute_roi structures from the compute_roi window. As well, any graph can be saved and/or printed.
next
This is the end of the basic ROI analysis. There is much more that can be done with your ROIs and which will be explained in the next chapter.