FS-FAST region of interest
instructions for use
written by nick knouf

Copyright © 2003, Nicholas Knouf & MIT.
ll rights reserved is manual may be reproduced as muchas you want m not going to restri your rights at all f you
post it on another website drop me a line okay r send me a
postcard  like getting mail o lawyers were involved in the
produion of this work ot tested as much as it can be  donthave that sort of budget lease dont sue me if it does something
bad to your machine
Set in Adobe Garamond Pro and News Gothic MT. Designed
using InDesign 2.0. Created on a Macintosh and OS X.

t able of content s
requirements getting and unpacking the source
installing the perl modules 
setup environment for froi 

introduction
froi







summary of analysis steps
a note on terminology

froi basics







creating an roi a note on logical roi naming 
editing an roi 
computing the roi average 
viewing your roi results next 
combining multiple rois 

further ROI tools

viewing roi overlap mapping an roi to the surface mapping a label to an roi 
combining labels 
creating and viewing a selectivity map listing rois 
creating and viewing a spatial activity profile

logfiles

roi formatsynopsis 
description 

mannual pages for scripts

chapter 0
installation

Installation of froi, while not a walk in the park, should not pose difficulties tothose who have installed the FS-FAST and Freesurfer distribution. Because of
the connection between froi and FS-FAST there is relatively minimal configuration needed to make the tools work.

re quirement s
froi has not been tested on a wide variety of platforms, but there is nothing thatshould prevent it from working in many places, including almost all Unices suchas Linux, xBSD, Darwin, Solaris, and Irix. It was developed on Linux running
Matlab 6.5 (R13) with perl version 5.6.1. I assume that it should work for all
versions of Matlab that work with FS-FAST and with versions of perl down to
5.2 or so. If you find any version incompatibilities, please let me know.

2chapter 0

get ting and unpacking thesource1.
You can download the source from the froi website, http://
froi.sourceforge.net.
2. Move the file to the directory just above where you want froi to live:
mv froi-source.tar.gz /usr/local
3. Unzip the distribution:
gunzip froi-source.tar.gz
Next untar the archive:
tar xvf froi-source.tar.gz
You will find a directory called “froi”. Within this directory is the complete
distribution, including some additional modules that need to be installed forfroi to work.

inst alling the perl modules
To help keep the design modular, and to allow future developers a reusable
framework, I created Perl modules that abstract a large amount of the code.
ese modules must be installed in a place that is accessible to the perl scriptsthat form the basis of the froi analysis.
ere are three modules to install (FSFAST::Parse, FSFAST::ROI, and FSFAST::Misc) and the procedure is the same for all.
1. Unzip and untar the module source:
gunzip module-name.tar.gz
tar xvf module-name.tar.gz
At this point you have two options. If you are the system administrator for thiscomputer, you can do the following to install the module into your system-wide
perl module directory:
2. Build the module and manual page:perl Makefile.plmakemake test
3. Change to root and install:su rootmake installIf, however, you are not the administrator and/or want to install the software ina non-standard place, you can do the following:
2. Tell the install script where to put the module; this location must be writableby you:perl Makefile.pl PREFIX=/place/to/install/module
3. Build the module and manual page and install:
makemake test
make install
At this point the module will exist under /place/to/install/module. To let perlknow the module exists, however, you have to do one more thing. You need to
set the environment variable $PERLLIB, which differs depending on what shell
you are using. For csh or tcsh, put the following in your .environment file:setenv PERLLIB /place/to/install/module/lib/site_perl/pervar/
where perlvar is your perl version, perhaps 5.6.1.
For other shells, consult the documentation to see how to set environment variables.
You will need to do this for each module in the distribution. Later releases will
streamline this into a single-step process.
note: e scripts assume perl is located at /usr/bin/perl; if it’s not there, you cancreate a symbolic link from /usr/bin/perl to your actual perl executable, or you
can change the shebang lines in each perl script. Again, later releases of froi willautomatically determine the location of perl.

installation3

4

chapter 0

setup environment for froiere are two final steps before you can use froi. First, you have to put the froi
scripts in your path. For csh or tcsh, type (replacing the location of froi withyour own location):set path = ( $path /usr/local/froi/bin)
For other shells, consult your documentation.
Finally, you have to tell matlab where to find the scripts. In your home directory
there should be a directory called “matlab”. If it doesn’t exist, create it. Withinthat directory, create or edit a file called “startup.m” and add the following:
addpath /usr/local/froi/toolbox
Again, replace the location of froi with your own installation directory.
At this point, logout and log back in again and you should be able to use froi!
If you have any problems, send a detailed description of the problem to froibugs@sourceforge.net.

chapter 1
introduction

reesurfer and  reesurfer unional nalysis tream are software
suites developed at the assachusetts eneral ospital imaging center for the
analysis of funional  f data insert freesurfer and fsfast refs is a set of tools for the analysis of slicebased f data including
preprocessing motion correion image normalization spatial smoothing
design specification including gamma and finite impulse response 
models contrast specification and statistical map creation n a complimentary
fashion reesurfer creates  surface and  volumebased reconstruionsof the brain ata from the slices can then be mapped onto a previous orcurrentsession anatomical or on a  surface such as an inflated or flattened
representation urfaces can also be registered into spherical and alairach
coordinate systemse advantages of  and reesurfer over other f analysis packages
are numerous e tight integration of the two complimentary suites provides
for relatively easy transformation of data from one representation to anothere majority of the programs are commandline based allowing for easy
scriptability as well as transparency of the analysis process for the user

6chapter 1

something that is sometimes difficult with other packages ith  andreesurfer there is no need for an individual subjes brain to be automaticallysmoothed and transformed into alairach space all analyses can be done in thesubjes native slicesowever  is lacking one major feature that being the analysis ofregions of interest s  analyses are an important part of funional research insert old nancy refs n  approach proceeds asfollows efine a funionallyspecific region by a localizer scan or example you
might be interested in areas that respond more to faces than to objes perhaps
the fusiform face area  insert  refs erform an experiment that tests your condition of interest for example
you might be interested in whether or not the  responds different to uprightfaces versus inverted faces sing the  defined in  look to see if there are any differences between
conditions in 
e advantages of an  approach are numerous or one because eachsubjes anatomy is different anatomical s are usually not sufficient formost analyses efining an independent funional  allows your analysis tobe tailored to the idiosyncrasies of the particular subjes brain s well since
you are only looking in a small region you do not have the problems associatedwith whole brain analyses  are there problems i think there are froi
o this end  wrote a suite of programs to do funional  analyses in
conjunion with  and reesurfer called froi   emeat of the suite is to allow one to funionally define s and then extra
information from the s such as mean timecourse for blocked data as wellas mean and percent signal change for each condition along with the associatedstandard deviations and errors s are saved in a spaceefficient format andcan be edited quite easily e results of an  computation can be viewed
using a atlab  and are saved in a atlab struure n addition there isan option to create tabdelimitted text files of the results for importation into
other programs like xcel or 
e funional definition of an  can be done in three ways by t value bysignificance sig value and by false discovery rate  insert  refsefining an  by t or sig value is done in a simple threshold fashion allvalues greater or lower in the case of negative values are taken to be in the sing  you provide a specific false discovery rate and a hypothesis of
how you think the noise is correlated and all voxels above the calculated
p value are included in the uch s should not be taken verbatim into the subsequent statistical analysis
however any times the s will include scattered and noncontiguous
voxels throughout your slices or may contain multiple funional regions thatyou would like to analyze separately fter masking the image with a tt sigor  threshold you need to edit the thresholded map in order to define
the appropriate s nce these s are created you are ready for further
statistical analysisata analysis within the  uses the results of the selxavg program of  selxavg computes the estimated deviation from baseline for eachcondition for each voxel in your volume epending on the type of analysis
either gammafit or  you may have only one point for each condition
gamma or a timecourse   analyses proceeds by averaging these dataover your  and computing the appropriate standard deviation and standard
error ese results can then be viewed or taken to a third level of analysis suchas a group analysis
froi provides many other  funions or example it can combine multiple
s up to three by interseion or union s well it can create an overlap
map of s up to three inally it can create a seleivity map for one
condition versus another thus allowing you to see how the seleivity of voxels
varies within and across sliceslicebased s provide a simple solution to the problem of converting yourdata to another coordinate system there is no problem owever there aresome times when you might want to view an  in a different coordinate
system for example to look at stability across sessions or to perform a group
analysis froi provides scripts to simplify these tasks t can take an  andconvert it into a reesurfer label while also taking a label and converting it toa froi  s well it can combine labels in much the same way as you can
combine s however as of the current release it only works for two labelsand only for the interseion method

introduction

7

chapter 2
summary ofanalysis steps

e following steps are common to  analysis with froi reprocess your data using 
 reate an analysis un seleive averaging un make_roi to create a simple thresholded  using tt sig or 
values mmediately after creating the thresholded  you will be given the
chance to edit it to your liking and save as a separate  urther edit your s as needed using edit_roi un compute_roi to compute the  average un view_roi_results to see the result of the  computation

10chapter 2

or some analyses you may want to consider one or more of the following
steps☞ reate further s as needed☞ ombine multiple s together and compute an  average
☞ reate an overlap map for multiple s and view using display_overlap☞ ompute seleivity indices and create a seleivity map for one condition
versus another☞ ransform your slicebased s to volume or surfacebased labels usingroi2label☞ ombine your labels using combine_label☞ onvert a volume or surfacebased label to a slicebased  usinglabel2roi☞ erform step  with your new chapter 3
froi basics

is chapter aims to explain the basics of using froi for the analysis of funional
data in association with  o begin however we need to speak thesame language

a note on terminolog ys with any new software package there is some new terminology to be learned
froi is no different et me explain some of the terms and abbreviations you will
see throughout this manual
analysis  name of an  analysis that has been run through at least theselxavgsess step
contrast  name of an  contrast that has been run through at least thestxgrindersess step

12

chapter 3

roianalysis  an  analysis that was used to create an 
func_path  path to your funional data n  parlance this would
default to session_direorysession_idbold
roi_path  path to your s y default this is session_direorysession_idboldroianalysis_ e addition of the  suffix is to easily differentiate thedireory in which your s are stored from the original  analysis
label_path  path to your labels created by make_label or roilabel is path
is by default session_direorysession_idboldroianalysis_label

creating an roi
o create an  use the make_roi program omplete documentation forthis program is presented in the ppendix  will outline a few specific cases
here
make_roi requires five parameters and accepts many more in most cases youwill give it more than the five required parameters e necessary parametersare analysis analysis_nameis is the name of a  analysis created after mkanalysissesshas been run contrast contrast_namee name of the contrast to use to create the  ese contrast maps
are created after you have run stxgrindersess roi roi_namee name you wish to give this  ee the seion below forsuggestions on how to name your s sf sessid_filee session  filename df sessdir_filee session direory filenameese five parameters will create a  that threshold your statistical map at asignificance value of  ometimes however you are interested in taking ahigher threshold or using a different statistical map n those cases you can give
one or more of the next three parameters map <t | sig>
e statistical map to use to create the  e default t statmaps are a tmap and a sigmap make_roi defaults to using the sig map threshold value
alue to use for the threshold unsigned
is parameter will consider your statistical map to be unsigned us
if you give a threshold for a tmap of  all voxels with a t value greater than  orless than  will be seleed for the s an alternative to thresholding the t or sig map  have implemented
thresholding by false discovery rate   insert ref and brief explanationof  
o use the  method you can give one or both of the following
parameters fdr valuealse discovery rate to use sually a  of  will give a reasonable see the references for some emperical studies np

is parameter indicates that you wish to use the nonparametriccalculations when using  ee the references for more details on when you
might want to use thisere 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 knowwhat you are doing as well these parameters have not been extensively testeda note on logic al roi naming
e method described above will create an  that is a simple threshold of
your contrast map any times this will include more voxels than you auallywant in your  ince it is impossible for the computer to know which areas
you want included in your final  you will need to sele a subset of thevoxels that are included in this initial  us make_roi immediately starts
edit_roi which allows you to edit this overbroad froi basics

13

14

chapter 3hen naming your initial  its useful to name it based on the statistical
map and threshold you are using f you are thresholding a t map with values
above  name your  using the roi parameter as tover f you are usingan  of  name your  fdr f course these are just guidelines but
it will help simplify things down the road

editing an roi
ollowing the creation of an  make_roi immediately starts edit_roi which
can also be ran on its own from the command line o use edit_roi requires
four parameters analysis
ame of the analysis used to create the  roiame of the  sf sessidame of the session  file df sessdir
ame of the session direory file
edit_roi begins with all voxels in the loaded  being seleed igure eleed voxels of the current  are shown in red while unseleed voxels of
the current  are shown in yellow o clear all the voxels press c to sele
all voxels press a ere are three modes in edit_roi to change your mode
press m one do nothing ele sele voxels
 eleesele sele a voxel if it is not seleed desele a voxel if it isseleeds well there are a number of different brush sizes you can use all the way
from x voxels up through x voxels o change the brush size press brepeatedly until you sele your desired brush sizeo simply the creation of s you can use the brush tool to sele relatively
large regions of cortex and then compute the interseion of those regions withthe underlying map us you do not have to be unnecessarily careful when

Figure 1. e top image shows the creation of a ROI thresholded at a significance value of 4 with all voxels selected. ebottom image is the same with all voxels deselected.

froi basics

15

16

chapter 3seleing your  simply type i to compute the interseion igure o save your  type s the default save location is in the direory func_dir
analysis_ ote that there is no need to add an extension for the filename
extensions are added automatically or detailed information about the 
format please see the appendixressing q will quit edit_roi and warn you if you have not saved your computing the roi average
nce your  is defined it is time to compute the average response over all thevoxels in the  e program that performs this computation is compute_roi is program works for both eventrelated and blocked data as well as for
gamma fitted and finite impulse response  analyses
compute_roi has similar syntax to both make_roi and edit_roi ere canbe confusion in the terminology so read the following descriptions of theparameters carefully analysis analysis_nameame of the analysis you wish to use for the  computation ou can use
one  for multiple analyses in fa this is one of the strengths of the approach f course the usual caveats apply in that you must have the same
slice prescription for all analyses that use the same us if you wanted to compute the  average over the voxels in the faceevent analysis you would use analysis faceevent for this parameter roianalysis roianalysis_nameame of the analysis under which you created your  ote the difference
between this parameter and the previous one is corresponds to the name of
the analysis used for your localizer runs perhaps faceblocked or different
 computations across different analyses but using the same  you would
use the same roianalysis name roi roi_namee name of the  to use in the computations sf sessid

Figure 2. Creating an ROI before (top) and after (bottom)
computing the intersection of the overlay (red).

froi basics

17

18

chapter 3

e name of the session  file df sessdir
e name of the session direory filecompute_roi will produce different results based on the nature of your analysisor example if you have a blocked analysis you will get the average raw time
course for your  in addition to amplitudes for each condition gammafit
analyses or timecourses eventrelated analyses ote that the raw timecourse
is just that raw without detrending or noise reduion or 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
ll of the results of compute_roi are saved in a atlab struure for easy access
ncluded in this struure is the results of the  computation information
regarding the analysis the  the number of voxels in the  etc isstruure can be accessed direly in order to view the results of the computation
f you prefer however you can use view_roi_results see next seion to see theresultsere are a few other parameters many of them similar to make_roi and edit_roi that can be passed to compute_roi  useful one is text this will output
the results of the  computation as text files for easy importation into otherprograms such as xcel or 
or more information see the compute_roi manual page either in the ppendix
or by typing compute_roi man

viewing your roi result s
ow that your  has been created and the  averages have been computed
you probably want to see the results e most dire way to do that is throughthe view_roi_results program igure  is will load the results of compute_roi and make them accessible through a atlab graphical user interface 
ou 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 igure  f your analysis was blocked you will
also be able to see the raw timecourse for each rune parameters for view_roi_results are similar to previous programs and areprobably familiar by now analysis analysis_nameame of the analysis you wish to use for the  computation roianalysis roianalysis_nameame of the analysis under which you created your  roi roi_namee name of your  sf sesside name of the session  file df sessdir
e name of the session direory fileote that you can load other compute_roi struures from the compute_roi
window s well any graph can be saved andor printed

nex t
is is the end of the basic  analysis ere is much more that can be donewith your s and which will be explained in the next chapter

froi basics

19

20

chapter 3

Figure 3. Graphical User Interface (GUI) for viewing ROI results. Top shows aninterface giving information about the ROI and allowing the user to select diff erent
plots to display. Bottom shows an interface to view average ROI raw time-courses
for blocked analyses.

Figure 4. Sample ROI results with standard errors given inscanner units (top) and percent signal change (bottom).

froi basics

21

chapter 4
further ROI tools

combining multiple rois
After using froi for a while, you will probably create a large number of ROIs.
What happens if you want to take two or three ROIs, say in a similar region,and combine them together? Or, say you have an anatomical ROI that probably
overlaps one of your functional ROI, and you only want to take those voxels in
the functional ROI that are also in your anatomical ROI?
ere exists a program called combine_roi that lets you do this. Allowing up
to three ROIs to be combined by either union or intersection, combine_roi will
output an ROI with the results of the operation. ese ROIs can then be usedjust like any other ROI, so you can edit it, compute the ROI average, etc.
One caveat; at the moment, all of the ROIs must be from the same analysis to
be used by combine_roi. If you have an ROI from a different analysis, you will
have to manually move it to your ROI directory.

24

chapter 4

e parameters for combine_roi are intuitive:
1. -roianalysis roianalysis_name
Name of the analysis used to create the ROI.
2. -inputroi ROI1,ROI2,ROI3
List of ROIs to combine. Note that the ROIs are separated by commas andthere is no space between the comma and the next ROI. If you don’t follow thisformat, then Bad ings will happen (where Bad ings are the program spitting out a cryptic error message and not working).
3. -outputroi roi_name
Name of the output ROI.
4. -method <union | intersection>
Method of combining ROIs. Giving the “union” option will take voxels thatappear in any input ROI, while intersection will only take the voxels that appear
in all input ROIs. us, union is like the set operation OR while intersection
is like AND.
5. -sf sessid, -df sessdir
Usual FS-FAST session ID and session directory filenames.
combine_roi will chug away and produce ROIs that are the result of your desired method.

viewing roi overlap
Say you have three conditions of interest, all of which are analyzed by an ROI
approach. At some point in your analysis you’re interested in whether or notthese ROIs overlap, if so, where, and if not, where are they separate. Using
combine_roi, you can create an overlap ROI which is then viewable using a
program called display_overlap. e only change to the command line for
combine_roi is:
4. -method overlap
Take the input ROIs and create an overlap ROI.

Once combine_roi is finished, you can view the results using display_overlap,
which has similar parameters to view_roi_results:
1. -analysis analysis_name
Name of the analysis you wish to use for the ROI computation.
2. -roianalysis roianalysis_name
Name of the analysis under which you created your ROI.
3. -roi overlaproi_namee name of your overlap ROI.
4. -sf sessid, -df sessdir
e usual FS-FAST session ID files and session directory files.
e colors depend on how many ROIs there are and which areas show overlap.
For two ROIs, the color key is:blue - ROI 1
red - ROI 2
white - overlap of both ROI
while for three ROIs the color key is:blue - ROI 1
red - ROI 2
yellow - ROI 3
purple - ROI 1 and ROI 2
orange - ROI 2 and ROI 3
green - ROI 1 and ROI 3
white - overlap of all ROIs
is color key is available also within the program by typing “c”.
As well, you can see a legend for each condition by typing “l”; thus you can see
what condition maps to which ROI. Basically, ROIs are taken in the order thatthey appeared on the command line in combine_roi.
display_overlap only works with up to three ROIs; any more, and the colormap for overlap becomes exponentially large. Anybody who wishes to impliment this for more than three ROIs, feel free to do so and send me a patch.

further roi tools

25

26

chapter 4

mapping an roi to the sur face
Slice-based ROIs are all well and good; they give you a subject-defined regionin which to do analyses. However, there are times that you’d like to look acrosssessions, or perhaps look in different spaces such as spherical, Talairach, or in an
average subject’s brain. For that, you might be interested as to where the ROI
lands in the volume or on the surface; this mapping of ROI to a surface- orvolume-based label is accomplished through roi2label.
roi2label requires, like all surface- or volume-based analyses, that the subject
in question have a reconstructed brain. As well, their functionals need to havebeen registered to this brain and there must exist a “subjectname” file with
the name of the subject’s reconstructed brain under the $SUBJECT_DIR, as
defined by your Freesurfer configuration files. erefore, before embarking onreconstructing every subject’s brain in a study, ensure that you need (and arewilling) to put in the time to reconstruct the brains.
roi2label has a relatively simple syntax with a couple pitfalls to be aware of:
1. -roianalysis roianalysis_name
Name of the analysis under which you created the ROI.
2. -roi roi_name
Name of the roi you’d like to map to a label.
3. -hemi <rh | lh>
Hemisphere you’d like mapped to a label.
4. -sf sessid -df sessdir
e usual session IDs and session directory files.
e main concern is to ensure that the hemisphere that you’d like to map your
ROI to actually has voxels in the ROI. For example, if your ROI is for the right
FFA, mapping that ROI to the left hemisphere is meaningless, as there are noleft hemisphere voxels in an ROI for the right FFA. Most times such a mistake
will be caught by the program and an error message will be displayed; however,if the program spits out a strange error message, be sure that you have not madesuch an error.
e labels are saved in a directory underneath your ROI directory named by de-fault “label”. e label filename is of the form: roiname-hemi.label, thus for an
roi rFFA and right hemisphere mapping, the label name will be rFFA-rh.label.

mapping a label to an roi
You can also go in the reverse direction. Perhaps you have a multi-subject labelthat you’d like to map to individual subject’s ROIs. It’s possible to transform
this label into an ROI using the program label2roi.
label2roi expects the label to be in your roi_analysis/label directory. e nameof the label should be in the format: stem-hemi.label, e.g., rFFA-rh.label. ecommand-line paramters are nearly identical to roi2label, only replacing the“-roi” parameter with “-label”:
1. -roianalysis roianalysis_name
Name of the analysis under which you created the ROI.
2. -label label_stem
Stemname of the label.
3. -hemi <rh | lh>
Hemisphere you’d like mapped to a label.
4. -sf sessid -df sessdir
e name of the resulting ROI will be the stem name of the label and will besaved in your roi_analysis directory.

combining labels
Much like with ROIs, you can also combine multiple labels together. At the
moment, not as much work has been put into combining labels as with combining ROIs, to the options are quite limited: you can take two labels and combine
them as one using intersection.
For more information see the combine_label manual page in the appendix orby typing “combine_label -man”.

further roi tools

27

28

chapter 4creating and viewing a
selec tivit y map
Selectivity maps are another useful way to view the results of your fMRI analysis. While the topic of selectivity inevitably leads to the question of what index
to use, intuitive indices can be used with excellent qualitative and quantitative
results.
For our purposes a selectivity index is simply a measure of how selective a particular voxel is for a particular condition. For example, you may want to know
which voxels are the most selective for faces; further, you would like to see how
this selectivity drops off as a function of distance in a functionally defined region. view_sm allows you do do this using one of several pre-defined selectivity
indices (user-defined indices are planned for a future release). e selectivity
indices included are:
1. (preferred - non-preferred)/(preferred + non-preferred)
2. (preferred - non-preferred)/(baseline)
3. (preferred - non-preferred)/(preferred + non-preferred) in percent signal
change4. abs(preferred - non-preferred)/ (preferred) in percent signal change
Preferred and non-preferred, for lack of better terms, refer to the conditions
in your selectivity index computation. For example, consider face selectivity(compared to objects). In this nomenclature, preferred would be faces and nonpreferred would be objects.
aside: I understand that the terms “positive’’ and “non-preferred’’ are not entirely clear, however I’m not sure of better alternatives. Please let me know if you
can think of better choices.
e actual computation of the selectivity map with view_sm is quite simple andfast. e command-line parameters to view_sm are:
1. -analysis analysis_name
Name of the analysis to use to compute the selectivity.
2. -preferred #e condition number (as defined in your paradigm file) for the “preferred’’
condition.

3. -non-preferred #e condition number for the “non-preferred’’ condition.
4. -sf sessid -df sessdir
e usual session ID and session directory files.
is will compute a selectivity map using the first selectivity index describedabove. As well, it will default to showing a 90% range of the selectivity values.
Since only a few voxels will show high selectivity indices, the distribution is
sharply peaked. Empirical testing has determined that a value of 90% for thisparameter, termed “-frac”, gives a good tradeoff between showing a decent
number of indices versus being conservative in the display. You can change thisparameter using:
5. -frac #Fraction of selectivity indices to show.
To choose a different selectivity index, use:
6. -type #Type of selectivity index to compute, where the type is given in the manpage.
e default view of the selectivity map is as a mosaic, but this can be changed
by typing “s’’ and entering a valid slice number.
Note that view_sm is rather new and has not been extensively tested.

listing rois
Trying to remember what analyses you have done is a constant problem when
dealing with large amounts of data. To help alleviate this problem, and to eliminate unnecessary digging through directories, I wrote a program called list_roi.
Given the name of your ROI analysis, your session ID file, and your session
directory file, list_roi will list all of the ROIs that have been created. For more
information, and for an example, see the list_roi manpage (via list_roi -man) or
the manpages in the Appendix.

further roi tools

29

30

chapter 4creating and viewing a spatial
ac tivit y profile
In displaying the results of fMRI analyses, most people show differences between conditions, commonly in a statistical map. However, this representationis twice-removed from the data: first there is the calculation of the difference
between two conditions; second is the determination of whether or not that difference is significantly different from zero, and the subsequent transformation
into a statistical value. Wouldn’t it be nice, on the other hand, to look at yourdata directly, without these intermediate steps?
I’ve developed a novel but intuitive way to look at your data, tentatively called
the Spatial Activity Profile (SAP). A SAP is a surface where the height at a point
is directly related to the magnitude of the signal at the point. When plotted for
all conditions in an experiment and on the same scale, the SAP allows you toquickly compare all conditions at once. As well, it’s now possible to see where
there are voxels that respond similarly to all conditions, suggesting that suchvoxels might be veinous rather than gray matter.
view_mesh impliments the display of SAPs. To narrow down the region todisplay, it is customary to use an ROI to mask a specific portion of the brain.
Note that the ROI must be rectangular, as it is presently impossible to display
a SAP in matlab with non-rectangular ROIs. us it would be good to take arectangular ROI around a specific functional region.
view_mesh requires the following arguments:
1. -roianalysis namee name of your ROI analysis.
2. -roi namee name of your rectangular ROI.
3. -sf sessid -df sessdir
e name of your session ID and session directory files, respectively.
For an example of a SAP, see Figure 4.1. e SAPs are labeled by condition;
the condition number refers to the condition number used in your paradigm
file. SAPs are displayed in the same scale for all conditions and plots, allowing
qualitative visual comparisons.

Figure 4.1. An example of a Spatial Activity Profile with five conditions in a region
encompasing the Fusiform Face Area. Each point represents a voxel with in-plane
resolution of 1.4mm. e conditions are, respectively, faces, scenes, objects, bodyparts, and scrambled objects.

further roi tools

31

appendix 1
logfilesInvariably, things will go wrong with your analyses and it will be your job tofigure out what happened, why it happened, and what to do to fi x it. To help inthis task, every program in froi writes a copious amount of data to logfiles. elogfiles are saved under the directory ``log’’ in the same directory from which
you run the scripts. Naming follows a predictible pattern:
program_name-ROIname-subjectName.log
e content of the logfiles is identical to what you would see on-screen if you
were to run the programs with the ``-debug’’ parameter. Each line is given adate and time, hopefully allowing you to track down what happened when. As
well, the logfiles also store the exact command-line used, thereby providing arecord of what commands were run and perhaps helping to diagnose strange
results.
In a future release I will add the ability for the logfiles to record matlab output,
thus hopefully making the debugging process even easier.

appendix 2
roi format

e format of the ROI files is quite simple: text-based, space-delimitted withfour columns. Each row of the ROI file corresponds to a particular voxel. ecolumns refer to:
1 - slice number of the voxel
2 - row coordinate of the voxel
3 - column coordinate of the voxel
4 - value at the voxel
Note that columns two and three refer to row and column values, not x and yvalues. Not keeping this distinction in mind will cause headaches down theroad; trust me, I’ve had them.
e fourth column, value, is normally 1, the exception being overlap ROIs,
where the values denote the type of overlap at that voxel. I also reserve the rightto use those values for other purposes in the future.
Planned later versions of the ROI format will require that the first line begin

36

appendix 2

with the pound character, after which will describe the dimensions of the functional volume.

appendix x
mannual pages
for scripts

combine _ label
combine_label -- takes two labels (three to come in the future) and combinesthem either by set intersection or union.

synopsiscombine_label -subjectname subjectname -inputlabel label1,label2 -outputlabel
output_label -method <intersection|union> [-labelpath $SUBJECTS_DIR/
label -force -help -man -debug]

description

38

appendix X

Much like with ROIs, it is sometimes useful to combine a two labels into one;for example, you might have labels for an anterior and posterior region andwant to combine them into one label (label union). As well, you may have twovertices that you think overlap and you want to see if they do and to create alabel that contains the overlaping vertices (label intersection). For example,
this would be the case if you had an anatomical label (the fusiform gyrus) andyou have a functional label (FFA) and want to know what vertices from thefunctional label lie within the anatomical label. combine_label allows the user
to do this.
e default search path for labels is under /subjectdir/funcdir/roidir/label/. If
you don’t want this, provide the -labelpath command-line option. Note that if
the directory does not exist it will be created.
e future goal is to have combine_label do the full suite of intersection, union,and overlap of 2-3 labels. At the moment, however, you can only do label intersection with two labels. Future work will implement the previous goal.

re quired ar g ument s- su bje c t n a me s u bje c t n a me
Name of the subject to which these labels belong. Even if using your own label
directory (i.e., not the label directory under $SUBJECTS_DIR), you need togive this parameter.
- i nput l a b e l l a b e l1, l a b e l 2
Name of the input labels, with or without the .label extension. Separate thelabels with a comma only, no spaces between the comma and the next label.
- out put l a b e l out put l a b e lName of the output label, with or without the .label extension. e labe will
be saved under $SUBJECTS_DIR/subjectname/label/ unless overridden by the-labelpath option.
- me t ho d i nt er s e c t
Method of label combination. intersect does simple set intersection and is the
only method currently supported.

optional ar g ument s- l a b e lp at h $ SU BJ E C TS _ DI R /s u bje c t n a me / l a b e l

Path in which to look for labels, -labelpath defaults to the label directory under
the subjectname. Change this if your labels are stored in a different location.
Note that input labels will be read from this directory and the output label will
be saved to this directory.
- f orc e
If you attempt to run combine_label for an output label that has previously beencreated, the program will quit with an error, telling you of this situation. Use
this parameter to override that behavior.
- he lp
Terse usage information.
-manComplete usage information (this file).
-debug
Displays debugging information. Use this option to help debug unexpectedbehavior and when submitting a bug report.

limit ations
As described above, combine_label only works currently for the method “intersection’’ and for two labels.

bugs
None known at the moment.

revision$Id: combine_label,v 1.3 2003/08/27 20:44:18 nknouf Exp $mannual pages for scripts

39

40

appendix X

combine _ roi
combine_roi -roianalysis roiAnalysisName -inputroi [ROI1,ROI2,ROI3, ...] outputroi roiName -method <intersection | union | overlap> -sf sessid -df sessdir[-maskdir masks -funcDir bold -force -help -man]
Type “combine_roi -man’’ for complete documentation

description
combine_roi allows one to combine multiple ROIs together quickly and easily.
If, for example, you have ROIs for left and right FFA, and have computed ROI
averages for each of those regions, but now want to consider the FFA together,irrespective of hemisphere, you can use combine_roi with the “union’’ method
to create a new ROI. As well, if you have an anatomical ROI and a functional
ROI, you can use combine_roi with the “intersection’’ method to get a new ROI
that is the intersection of those two ROIs. us, “intersection’’ is like “AND’’and “union’’ is like “OR’’.
As well, combine_roi can also be used to create an “overlap’’ ROI. is ROI is
specially coded to show how up to three ROIs overlap. is is extremely usefulif, for example, you have functionally defined three areas with different tasks
and want to know if the areas overlap. To view the results, you can use theprogram display_overlap .
Note that when giving the list of input ROIs to combine, the names must be
separated by commas, with no space in between the comma and the next ROI.
See the example below for more details.
ROIs created by combine_roi are viewable and editable using edit_roi .

ar g ument s
re quired ar g ument s- r oi a n a l y si s r oi A n a l y si sNa me
Name of the analysis from which you computed the ROI. Do not use in conjunction with -maskdir .

- i nput ROI r oi L i s t
List of ROI names, delimited by commas, e.g., ROI1,ROI2,ROI3. Note thatyou cannot have a space inbetween the “,’’ and the next ROI in the list.
- out put ROI r oi Na me
Name of the ROI in which to put the output.
- me t ho d < i nt er s e c t ion | u n ion | ov erl a p >Name of the method to use when combining the ROIs. “intersection’’ will only
consider a voxel to be part of the output ROI if it was in all of the input ROIs,
while “union’’ will consider a voxel to be part of the output ROI if it was inany one (or more) of the input ROIs. us, “intersection’’ is like AND while“union’’ is like OR.
“overlap’’ is different than the other two. If you use “-method overlap’’, combineROI will take the input ROIs (to a maximum of three) and compute theareas that are distinct and overlap. e order of your ROIs on the commandline determines the colors that are used to determine the distinct and overlaping
areas. You can display the resulting map using displayOverlap . e colors are
as follows:
2 ROIs: blue - condition 1 | red - condition 2 | white - overlap of both conditions
3 ROIs: blue - condition 1 | red - condition 2 | yellow - condition 3 | purple- condition 1 and condition 2 | orange - condition 2 and condition 3 | green- condition 1 and condition 3 | white - overlap of all conditons- s f s e s sid f i leName of the session ID file. Note that only one session ID in the file will be
used (the last one)
- d f s e s s d i r f i leName of the session directory file.

optional ar g ument s-maskdir masks
Name of the directory under the bold directory funcDir to hold your ROIs.
Defaults to analysisName_ROI , so if your analysis is called hfso, the mask directory would be called hfso_ROI and made underneath the bold directory.

mannual pages for scripts

41

42

appendix X- f u nc d i r b old
Name of the directory holding the functional runs. Usually “bold’’, defaults to“bold’’.
- f orc e
If an roi named roiName already exists, combineROI will quit. Use this option
to override this behavior, but be warned that it will overwrite the existing ROI.
- he lp
Provides complete argument information.
-man
Provides verbose usage information.
- de bu g
Provides complete debugging information.

bugs
None known of. Send bug reports to < froi-bugs@sourceforge.net >.

revision$Id: combine_roi,v 1.8 2003/08/27 20:44:18 nknouf Exp $compute _ roi
compute_roi -analysis analysisName -roianalysis roiAnalysisName -roi roiName -sf sessidfile -df sessdirfile [-funcstem fmc -funcdir bold -outputstem
roiName -maskdir analysisName_ROI -force -help -man]
Type “compute_roi -man’’ for complete documentation

description

compute_roi takes a previously created ROI (commonly from make_roi and/or
edit_roi ) and, with a FS_FAST analysis, computes the average time-course
over the ROI for each run in the analysis. is time course is saved as a Matlab
structure in the ROI directory. Text file output (for importing into other programs) can be done using the -text argument.
To view the results, use view_roi_results .
compute_roi warns the user if there already exist computed and saved timecourses for this ROI; using the -force option will allow the user to overwrite
those time courses.
NOTE: You must have the correct number of conditions for analysis analysisName , otherwise compute_roi will not work. e fsfast processing stream
will work without the correct number of conditions being specified, but compute_roi will not, as it uses that value for some of its processing.

ar g ument s
re quired ar g ument s- a n a l y si s a n a l y si sNa me
Name of a FS-FAST analysis- r oi a n a l y si s r oi A n a l y si sNa me
Name of the analysis from which you created the ROI. Do not use in conjunction with -maskdir .

- r oi r oi Na me
Name of the ROI to use in the computations.
- s f s e s sid f i leName of the session ID file. Note that only one session ID in the file will be
used (the last one)
- d f s e s s d i r f i leName of the session directory file.

mannual pages for scripts

43

44

appendix X

optional ar g ument s- f u nc d i r b old
Name of the directory holding the functional runs. Usually “bold’’, defaults to“bold’’.
- f u nc s t em f mc
Name of the functional stem from which to create the base. Defaults to fmc.
- out put s t em r oi Na me
Name of the output stem of the computed ROI data. Defaults to the name of
the ROI.
-maskdir masks
Name of the directory where the ROI is saved. Only use if you saved data toa non-standard location when running makeROI . e default is to use the-roianalysis option to get the directory roiAnalysis_ROI . Do not use in conjunction with -roianalysis .
-text
If you give the -text paramter, compute_roi will output text files containing
the computed time courses and estimated ROI responses in addition to Matlab
structure. is is useful for direct importing into other programs, such as Excel
or SPSS. Defaults to text files not being saved.
- f orc e
If ROI time courses with names of the type analysis_roi_typetxt already exists(for example, if you have previously ran compute_roi on these data), compute_roi will quit. Use this option to override this behavior, but be warned that it will
overwrite the existing time courses.
- he lp
Provides complete argument information.
-man
Provides verbose usage information.
- de bu g
Provides complete debugging information.

det ails of result se Matlab structure will be called “ROIs’’ and will have a number of fields,
some with information about the analysis and ROI computation, some with theresults of compute_roi . e contents of the resulting structure (and thus, theresults of the computation) depend on the analysis. For analyses with the gammafit parameter, you can expect the following:
BlockedROIs.ROImean: mean time course for each run. Note that this is the raw
time-course before detrending (because FS-FAST does not save detrended data
currently).
ROIs.ROIhavg, ROIs.ROIhstd, ROIs.ROIhstderr: Mean, standard deviation,and standard error, respectively, of the estimated deviation from baseline foreach condition within the ROI.
ROIs.ROIpct, ROIs.pctstd, ROIs.pctstderr: Percent signal change, standard
deviation, and standard error, respectively, for each condition.
Event-related
ROIs.ROIhavg, ROIs.ROIhstd, ROIs.ROIhstderr: Mean, standard deviation,and standard error, respectively, of the estimated deviation from baseline foreach condition within the ROI.
ROIs.ROIpct, ROIs.ROIpctstd, ROIs.ROIpctstderr: Percent signal change,
standard deviation, and standard error, respectively, for each condition.
For FIR analyses, the computations create the same data for both blocked andevent-related analyses:
Blocked & Event-related
ROIs.ROImean, ROIs.ROIstd, ROIs.ROIstderr: Mean, standard deviation,and standard error, respectively, of the estimated hemodynamic response function for each condition.
ROIs.ROIpct, ROIs.ROIpctstd, ROIs.ROIpctstderr: Percent signal change,
standard deviation, and standard error, respectively, of the estimated hemodynamic response function for each condition.
Note that for all of these results (with the exception of the average time-courses
for the runs), fixation is the first condition.
A note on the directory structure: compute_roi expects either the -roianalysis
or the -maskdir command line options. e first is used if using the default
storage location for the ROIs (i.e., under the functional directory). If you givethe option as -roianalysis hfso ,compute_roi will expect to find the roi roiName
under bold/hfso_ROI . Use the option -maskdir when your ROI is not saved

mannual pages for scripts

45

46

appendix X

in this format.

tex t output
e contents of the saved text files are as follows (stem: contents): mean: meantime course; std: standard deviation of “mean’’; stderr: standard error of “mean’’;pct: percent signal change; pctstd: standard deviation of “pct’’; pctstderr: standard error of “pct’’; havg: estimated max responses (only for blocked); hstd:
estimated standard deviation (only for blocked); hstderr: estimated standard
error (only for blocked).

bugs
None known of. Send bug reports to < froi-bugs@sourceforge.net >.

revision$Id: compute_roi,v 1.13 2003/08/27 20:44:18 nknouf Exp $display_ overlap
display_overlap -roianalysis analysisName -roi roiName -sf sessid -df sessdir[optional arguments]
Type “display_overlap -man’’ for complete documentation

description
display_overlap displays an overlap map of two or three ROIs. Such a map iscreated when you run combine_roi with the argument -method overlap . ese
overlap maps allow you to see exactly what ROIs overlap, where they overlap,
and what areas are distinct for each ROI. e Matlab script provides a way to
see the name of the ROIs used to create the overlap map as well as a legend of
the colors. To find out more information, press hto get a help window.

ar g ument s
re quired ar g ument s- r oi a n a l y si s a n a l y si sNa me
Name of a FSFAST analysis- r oi r oi Na me
Name of the overlap ROI- s f s e s sid f i leName of the session ID file. Note that only one session ID in the file will be
used (the last one)
- d f s e s s d i r f i leName of the session directory file.

optional ar g ument s- r oid i r m a s k sName of the directory under the analysis roiAnalysisName to hold your ROIs.
Defaults to roiAnalysisName_ROI (e.g., for an analysis called “hfso’’, the ROI
directory defaults to “hfso_ROI’’).
- b a s e r u n Di r e c t or y
Use this functional directory as the base upon which to display the overlap map.
Only needs to be taken into consideration if you used different number of slices
or different slice prescriptions for different runs of your scan. Defaults to thefirst bold directory.
- f u nc Di r b old
Name of the directory holding the functional runs. Usually “bold’’, defaults to“bold’’.
- f u nc St em f mc
Name of the functional stem from which to create the base. See -base . Defaults to fmc.
- he lp

mannual pages for scripts

47

48

appendix X

Provides complete argument information.
-man
Provides verbose usage information.
- de bu g
Provides complete debugging information.

exampledisplay_overlap -roianalysis lohfso2 -roi FFAoverlap -sf sessid -df sessdir

bugs
None known of. Send bug reports to < froi-bugs@sourceforge.net >.

revision$Id: display_overlap,v 1.6 2003/08/27 20:44:18 nknouf Exp $edit _ roi
edit_roi -analysis analysisName -roi roiName -sf sessid -df sessdir [optional
arguments]
Type “edit_roi -man’’ for complete documentation

description
edit_roi allows one to edit a previously created ROI. Such an ROI is commonly
created from a program like make_roi . Multiple ROIs can be saved, as the
program will use the input ROI as a template from which to save further ROIs.
e program thus allows one to take a large ROI, like a “p values smaller than
10 -4 map and divide it into smaller ROIs.

edit_roi starts Matlab with your input ROI displayed over the first run in yourbold directory or the first run in your runlist (if you have defined a runlist).
At first all voxels in the input ROI will be selected and in red. To erase all theselected voxels and to start from a blank ROI, press “c’’. You will see that all of
the voxels are now yellow, indicating that no voxels are selected for the current
ROI. e yellow voxels indicate the input ROI and are used as a template whencreating further ROIs.
To ease creation of ROIs, you can use a large brush size to select voxels and thenpress “i’’ to take the intersection of your brush selection and the underlying
template.
ere is more complete help information within the program itself; press “h’’to read it.

ar g ument s
re quired ar g ument s- a n a l y si s a n a l y si sNa me
Name of a fsfast analysis- r oi r oi Na me
Name of the ROI to edit
- s f s e s sid f i leName of the session ID file. Note that only one session ID in the file will be
used (the last one)
- d f s e s s d i r f i leName of the session directory file.

optional ar g ument s- ov erl ay ov erl ay Na me
Name of the ROI to overlay on top of the ROI named with the -roi parameter.
Most often this is used to make further edits to, e.g., an “FFA’’ ROI on top of a“t greater than 4’’ ROI.

mannual pages for scripts

49

50

appendix X- r oid i r m a s k sName of the directory under the analysis analysisName to hold your ROIs.
Defaults to analysisName_ROI (e.g., for an analysis called “hfso’’, the ROI
directory defaults to “hfso_ROI’’).
- b a s e r u n Di r e c t or y
Name of a different base directory on which to overlay the template and ROIs.
Only needs to be taken into account if you used different slice prescriptions
within the same scan. Defaults to the first run in the bold directory or the firstrun in your runlist (if you have that defined).
- f u nc Di r b old
Name of the directory holding the functional runs. Usually “bold’’, defaults to“bold’’.
- f u nc St em f mc
Name of the functional stem from which to create the base. See -base . Defaults to fmc or the functional stem in your analysis.info file.
- he lp
Provides complete command information.
-man
Provides verbose usage information.
- de bu g
Provides complete debugging information.

exampleedit_roi -analysis blocked -roi ffa -sf sessid -df sessdir

bugs
None known of. Send bug reports to < froi-bugs@sourceforge.net >.

revision$Id: edit_roi,v 1.9 2003/08/25 23:31:55 nknouf Exp $label2roi
label2roi -roianalysis roi_analysis_name -label label_name -hemi <rh|lh> -sf
sessid_file -df sessdir_file [-labeldir roianalysis_ROI/label -bolddir bold -maskdir roianalysis_ROI -funcstem fmc -outputstem roi-hemi -force -help -man-debug]description
Surface-based ROI analyses in Freesurfer are performed using labels, which aresimply a list of marked vertices. Using the tools in tksurfer , it is quite easy todraw labels that encompass various anatomical regions. With a program likecombine_label , you can take two labels and create either the intersection and/or
union of the labels. What if, however, you’d like to see where these labels landon the slices?
label2roi exists to transform a surface- or volume-based label into a slice-based
ROI. It uses the Freesurfer program mri_surf2vol to do most of its work. Notethat this assumes you have done the following:
Reconstructed the subject’s brain.
Registered the current session to the previous session anatomicals that were used
to reconstruct the brain.
Created a subjectname file, as described in the FS-FAST documentation.
One must be careful when using this program; if, for some reason, your sliceprescription does not include the region within the label, the program will failwith an error.
e label filename must be in a certain format. e label filename must be of
the form: label-hemi.label, where “label’’ is the name given with the -label flag,and “hemi’’ is the hemisphere given with the -hemi flag. For example, if you
have a right hemisphere fusiform label, your label file should called “fusiformrh.label’’, and your command line arguments would be “-label fusiform -hemirh’’. label2roi will create an roi named “label.roi’’, so in the previous example, itwould create “fusiform.roi’’.

mannual pages for scripts

51

52

appendix X

ar g ument s
re quired ar g ument s- r oi a n a l y si s r oi _ a n a l y si s _ n a me
Name of the analysis under which you created the ROI and subsequently created labels. label2roi will search for labels under roidir/label.
- l a b e l l a b e l _ n a me
Stem name of the label.
- hem i < rh|l h >Hemisphere from which to map the label. Note that if you try and map a label
from a hemisphere to a slice prescription that does not contain the label, theprogram will fail with an error.
- s f s e s sid _ f i leName of the session ID file.
- d f s e s s d i r_ f i leName of the session directory file.

optional ar g ument s- pr ojf r a c 0
Fraction [0, 1] of the cortical thickness at each vertex to project along the su
rface normal. e default is 0. Change this to project more of your data onto
the cortical surface, as the default is to sample only at the grey-white boundary.
- l a b e ld i r r oi _ a n a l y si s _ ROI / l a b e l
Directory from which to search for the input label. Defaults to a directory
called “label/’’ underneath your ROI analysis directory.
- b old d i r b old
Name of the functional directory. Defaults to “bold’’.
- m a s k d i r r oi a n a l y si s _ ROIName of the directory that holds the resulting ROI. Defaults to <roianalysis_

ROI>; set this argument if you save your data in a non-standard location. Do
not use in conjunction with -roianalysis .
- f u nc s t em f mc
Name of the functional stem. Defaults to “fmc’’. Change this if, for example,
you have separate functional volumes for smoothing and want to create ROIs
from that data.
- out put s t em r oi - hem iName of the stem for the output label. Defaults to roi-hemi , making the output file <roi-hemi.label>.
- f orc e
If you attempt to run label2roi for a ROI that has previously been created, theprogram will quit with an error, telling you of this situation. Use this parameterto override that behavior.
- he lp
Terse usage information.
-manComplete usage information (this file).
- de bu g
Displays debugging information. Use this option to help debug unexpectedbehavior and when submitting a bug report.

bugs
None known of. Send bug reports to < froi-bugs@sourceforge.net >.

revision$Id: label2roi,v 1.4 2003/08/25 23:30:15 nknouf Exp $mannual pages for scripts

53

54

appendix X

list _ roi
list_roi -roianalysis roianalysis_name -sf sessid -df sessdir [optional arguments]

description
When performing many ROI analyses it’s sometimes hard to remember what
ROIs have been created. list_roi exists to simply list the ROIs in a given roi
analysis directory.

ar g ument s
re quired ar g ument s- r oi a n a l y si s r oi a n a l y si s _ n a me
Name of the analysis used to create the ROIs. Do not use in conjunction with-maskdir .
- s f s e s sid f i leName of the session ID file. Note that only one session ID in the file will be
used (the last one)
- d f s e s s d i r f i leName of the session directory file.

optional ar g ument s-maskdir mask _dir
Use this when you have stored your ROIs in a non-standard location.
- he lp
Provides complete argument information.
-man
Provides verbose usage information (this document).

- de bu g
Provides complete debugging information.

revision$Id: list_roi,v 1.3 2003/08/27 20:44:18 nknouf Exp $make _ label
make_label -analysis analysis_name -contrast contrast_name -hemi <rh|lh>-sf sessid_file -df sessdir_file [-map t -threshold 2 -type signed -bolddir bold-maskdir roianalysis_ROI -funcstem fmc -outputstem roi-map-hemi -force help -man -debug]

description
Sometimes it is useful to take a ROI and convert it into a surface-based label;for that, we have roi2label . Other times, however, we want to easily transforma previously computed contrast into a surface-based *.w file as well as a label. To
do that, we can use make_label . It is required to apply a threshold to the contrast data; otherwise many more vertices will be included in the label than the
research would like. e default threshold is “2’’, so for t-maps this means thatt values greater than 2 will be included in the label, while for a sig map, sig values greater than 2 (and thus, smaller than 10^-2) will be included. make_label
defaults to using signed quantities; to use unsigned, add the argument “-type
unsigned’’.
To use make_label you must have a reconstructed brain for the subject in question, a “subjectname’’ file under their session directory with the name of thereconstructed subject’s name inside, and a “register.dat’’ file under their bolddirectory. is thus assumes that you have run either autoreg-sess or tkregistersess on this subject to create the “register.dat’’ file. Registering and reconstructing a brain takes a fair amount of time on the part of the researcher and thus
should probably only be done with long-term or repeat subjects.
ere are some provisions for storing data in non-standard locations. See theoptions below for more information.

mannual pages for scripts

55

56

appendix X

re quired ar g ument s- a n a l y si s a n a l y si s _ n a me
Name of the analysis for the contrast in question.
- c ont r a s t c ont r a s t _ n a me
Name of the contrast to transform into a label.
- hem i < rh|l h >Hemisphere on which to map the ROI. Note that if you try and map an ROIfrom a hemisphere for which there are no voxels, the program will fail, oftentimes without a useful error message.
- s f s e s sid _ f i leName of the session ID file.
- d f s e s s d i r_ f i leName of the session directory file.

optional ar g ument s-map tStatistical map to transform to a label. Defaults to “t’’.
- t h r e s hold 2
reshold to use when transforming the contrast to a label. Defaults to 2.
- t y p e si g ne d
Whether to use signed or unsigned quantities when thresholding the contrast.
Defaults to “signed’’.
- pr ojf r a c 0
Fraction [0, 1] of the cortical thickness at each vertex to project along the su
rface normal. e default is 0. Change this to project more of your data onto
the cortical surface, as the default is to sample only at the grey-white boundary.
- b old d i r b old
Name of the functional directory. Defaults to “bold’’.

- m a s k d i r r oi a n a l y si s _ ROIName of the directory that holds the ROIs. Defaults to <roianalysis_ROI>; set
this argument if you save your data in a non-standard location. Do not use inconjunction with -roianalysis .
- f u nc s t em f mc
Name of the functional stem. Defaults to “fmc’’. Change this if, for example,
you have separate functional volumes for smoothing and want to create ROIs
from that data.
- out put s t em r oi - m a p - hem iName of the stem for the output label. Defaults to roi-map-hemi , making theoutput file <roi-map-hemi.label>.
- f orc e
If you attempt to run roi2label for a label that has previously been created, theprogram will quit with an error, telling you of this situation. Use this parameterto override that behavior.
- he lp
Terse usage information.
-manComplete usage information (this file).
- de bu g
Displays debugging information. Use this option to help debug unexpectedbehavior and when submitting a bug report.

bugs
e “subjectname’’ file must contain only one line: the name of the subject. If
there are one or more empty lines after the subject’s name, the program will
fail.

revision$Id: make_label,v 1.4 2003/08/27 20:44:18 nknouf Exp $mannual pages for scripts

57

58

appendix X

make _ roi
make_roi -analysis analysis_name -contrast contrast_name -roi roi_name -sf
sessid -df sessdir [optional arguments]
Type “make_roi -man’’ for complete documentation.

description
e first step in an ROI analysis is to define the ROI. make_roi allows one to dothat by thresholding a statistical map. resholds can be applied to either the tor significance map. As well, you can use the false discovery rate (FDR) technique to select your significance value threshold. ** insert FDR reference**
Most of the time, however, you don’t want to simply include all voxels that passa certain threshold in an ROI. Rather, you want the voxels that pass a threshold
and are clustered together in a specific anatomical region. us, after the creation of the thresholded ROI, make_roi allows you to edit this ROI (using thesame tools as in edit_roi ) to select and create ROIs based on your thresholded
ROI. ese are the ROIs that you will most likely use in further processing.
You can get help when editing the ROI by typing “h’’. Voxels in your current
ROI are in red, while voxels that are not in your current ROI but are in thethresholded ROI are in yellow.
ere are many options available for make_roi that influence later processing;please read the ARGUMENTS section for more details.

ar g ument s
re quired ar g ument s- a n a l y si s a n a l y si sNa me
Name of a fsfast analysis- c ont r a s t c ont r a s t Na me
Name of a fsfast contrast

- r oi r oi Na me
Name you wish to give this ROI- s f s e s sid f i leName of the session ID file. Note that only one session ID in the file will be
used (the last one)
- d f s e s s d i r f i leName of the session directory file.

optional ar g ument s- m a p t , si g
Stat map for contrast contrastName to load. As of writing, the code has beentested only minimally for sig maps. Defaults to sig maps.
- fd r v a lue
Instead of thresholding by a simple tor pvalue, threshold using False Discovery
Rate (FDR). **insert ref** e default is to choose the p value that makes
assumptions about the correlations of the data (that they are independent or
positively dependent); these assumptions are usually valid with fMRI data.
Making these assumptions gives you a more liberal pvalue than when making
no assumptions. If you would like to make no assumptions add the -np parameter, described below. At the moment, this only applies the FDR pvalue to sig
maps.
- np
When given, make no assumptions about the independence or dependence ofyour data. Add this paramter in addition to -fdr (described previously) if you
have questions about the independence of your data.
- t h r e s hold v a luereshold to use when creating ROI from stat map. For both t and sig(aka,F) maps, all voxels with t (or F) values greater than this value will be included.
Defaults to 2. See -map
- b a s e r u n Di r e c t or y
When running the matlab function editOverlay , use this functional directoryas the base upon which to overlay the mask. Only needs to be taken into consideration if you used different number of slices or different slice prescriptions
for different runs of your scan. Defaults to the first bold directory.

mannual pages for scripts

59

60

appendix X- f u nc Di r b old
Name of the directory holding the functional runs. Usually “bold’’, defaults to“bold’’.
- f u nc St em f mc
Name of the functional stem from which to create the base. See -base . Defaults to fmc.
-maskdir masks
Name of the directory under the bold directory funcDir to hold your ROIs.
Defaults to analysisName_ROI , so if your analysis is called hfso, the mask directory would be called hfso_ROI and made underneath the bold directory.
- (no) si g ne d
Determines whether to take signed or unsigned values for the thresholding. If-signed , voxels will be selected that are above (below) the threshold for positive (negative) thresholds. Use -nosigned when you don’t care about the sign ofthe stats (i.e., when you want to take all the voxels that satisfy abs(statistics) >abs(threshold)). Defaults to -signed . See also -unsigned .
- u n si g ne d
Use unsigned values for thresholding. Do not use with -signed . See also (no)signed .
- f orc e
If an roi named roiName already exists, makeROI will quit. Use this option to
override this behavior, but be warned that it will overwrite the existing ROI.
- he lp
Provides complete command information.
-man
Provides verbose usage information.
- de bu g
Provide complete debugging information.

bugs
e code has not been extensively tested with using the -unsigned option inconjunction with -fdr .

revision$Id: make_roi,v 1.13 2003/08/27 14:57:56 nknouf Exp $roi2label
roi2label -roianalysis roi_analysis_name -roi roi_name -hemi <rh|lh> -sf sessid_file -df sessdir_file [-labeldir roianalysis_ROI/label -bolddir bold -maskdir
roianalysis_ROI -funcstem fmc -outputstem roi-hemi -force -help -man -debug]

description
Slice-based ROIs (which are made by make_roi and/or edit_roi) are usefulwhen you want to look at ROIs within a particular subject within a particularsession; they eliminate the distortions caused by transformation into anotherspace, such as Talairach or spherical. However, there are times when you mightwant to look at ROIs over multiple sessions, or wants to compare ROIs acrosssubjects in another space. To that end, roi2label exists to transform a slicebased ROI into a surface-based label.
To use roi2label you must have a reconstructed brain for the subject in question,a “subjectname’’ file under their session directory with the name of the reconstructed subject’s name inside, and a “register.dat’’ file under their bold directory. is thus assumes that you have run either autoreg-sess or tkregister-sesson this subject to create the register.dat file. Registering and reconstructing a
brain takes a fair amount of time on the part of the researcher and thus should
probably only be done with long-term or repeat subjects.
Labels are saved under the roi directory of the subject, within a directory called“label’’. Note that if you then want to compare labels across different sessions or
subjects (for example, with the combine_label program), you will need to movethe label(s) into a common location.
roi2label uses the Freesurfer program “mri_vol2surf’’ for the mapping of slice-

mannual pages for scripts

61

62

appendix X

based data to a surface-based representation.
Note that the program will fail with an error if there are no vertices in the
resulting mapping. If this occurs, ensure that you are mapping to the correct
hemisphere, as this is an easy place to make a mistake.

ar g ument s
re quired ar g ument s- r oi a n a l y si s r oi _ a n a l y si s _ n a me
Name of the analysis under which you created the ROI.
- r oi r oi _ n a me
Name of the ROI.
- hem i < rh|l h >Hemisphere on which to map the ROI. Note that if you try and map an ROIfrom a hemisphere for which there are no voxels, the program will fail with anerror.
- s f s e s sid _ f i leName of the session ID file.
- d f s e s s d i r_ f i leName of the session directory file.

optional ar g ument s- pr ojf r a c 0
Fraction [0, 1] of the cortical thickness at each vertex to project along the surface normal. e default is 0. Change this to project more of your data onto thecortical surface, as the default is to sample only at the grey-white boundary.
- l a b e ld i r r oi _ a n a l y si s _ ROI / l a b e l
Directory where you want the output label to be stored. Defaults to a directory
called “label/’’ underneath your ROI analysis directory.
- b old d i r b old

Name of the functional directory. Defaults to “bold’’.
- m a s k d i r r oi a n a l y si s _ ROIName of the directory that holds the ROIs. Defaults to <roianalysis_ROI>; set
this argument if you save your data in a non-standard location. Do not use inconjunction with -roianalysis .
- f u nc s t em f mc
Name of the functional stem. Defaults to “fmc’’. Change this if, for example,
you have separate functional volumes for smoothing and want to create ROIs
from that data.
- out put s t em r oi - hem iName of the stem for the output label. Defaults to roi-hemi , making the output file <roi-hemi.label>.
- f orc e
If you attempt to run roi2label for a label that has previously been created, theprogram will quit with an error, telling you of this situation. Use this parameterto override that behavior.
- he lp
Terse usage information.
-manComplete usage information (this file).
- de bu g
Displays debugging information. Use this option to help debug unexpectedbehavior and when submitting a bug report.

bugs
None known at the moment. “mri_vol2surf’’ sometimes gives a warning of theform “voxel size not the same’’; I have not tested to see if this causes problems ornot. Send bug reports to < froi-bugs@sourceforge.net >.

revision$Id: roi2label,v 1.6 2003/08/27 20:44:18 nknouf Exp $mannual pages for scripts

63

64

appendix X

view_ mesh
Manual information to come soon.

view_ roi _ result s
view_roi_results -analysis lohfso -roianalysis lohfso -roi ffa -sf sessid -df sessdir[optional arguments]
Type “view_roi_results -man’’ for complete documentation

description
Running compute_roi to compute an ROI average creates a number of data
sets, viewing of which can be somewhat tedious. is is where view_roi_results
comes in. is script, which starts a Matlab GUI, allows one to easily view theresults of an ROI computation. us, for blocked runs, you will be able to viewthe raw time course over the ROI, the estimated deviation from baseline (anderrors) and the estimated percent signal change (and errors); for event-related,
you will be able to view the estimated time-course (and errors) in both raw scanner units and percent signal change.
Within the GUI, click on the help menu to get more information. If, at sometime when running view_roi_results , you want to load another data structure,
you can do this from the “File...Open...’’ menu option.

ar g ument s
re quired ar g ument s- a n a l y si s a n a l y si sNa me
Name of a fsfast analysis

- r oi a n a l y si s r oi A n a l y si sNa me
Name of the analysis from which you computed the ROI. Do not use in conjunction with -maskdir .
- r oi r oi Na me
Name of the ROI whose results you want to view.
- s f s e s sid f i leName of the session ID file. Note that only one session ID in the file will be
used (the last one)
- d f s e s s d i r f i leName of the session directory file.

optional ar g ument s-maskdir masks
Name of the directory where the ROI is saved. Only use if you saved data toa non-standard location when running make_roi . e default is to use the-roianalysis option to get the directory roiAnalysis_ROI . Do not use in conjunction with -roianalysis .
- he lp
Provides complete argument information.
-man
Provides verbose usage information.
- de bu g
Provides complete debugging information.

exampleview_roi_results -analysis lohfso -roianalysis lohfso -roi ffa -sf sessid -df sessdir.

bugs
None known; send an e-mail to < froi-bugs@sourceforge.net > for bug reports.

mannual pages for scripts

65

66

appendix X

revision$Id: view_roi_results,v 1.3 2003/08/27 20:44:18 nknouf Exp $view_ sm
view_sm -analysis analysis_name -preferred # -non-preferred # -sf sessid -df
sessdir [-frac # -type # -funcdir -help -man -debug]
Type “view_sm -man’’ for complete documentation

description
Selectivity indices provide a means for determining the “selectivity’’ of particularvoxels. In this case, selectivity means a measure of how much a voxel responds
to one condition (denoted here as the “preferred’’ condition) versus another condition (denoted here as the “non-preferred’’ condition). While statistical maps
provide a description of areas that are active versus another condition, selectivity
maps (and the corresponding indices) provide a description of how well a voxel
is tuned for a particular condition.
Consistent formulas for determining selectivity are not present in the literature;
however, there are some that make more sense than others. Currently two formulas are implimented, with plans for user-defined indices in the future:
1. (preferred - non-preferred)/(preferred + non-preferred)
2. (preferred - non-preferred)/(hemodynamic offset of the voxel)
In order to provide meaningful values, instead of using percent signal change orother measures (which might be below zero), view_sm uses the hemodynamic
values calculated from FS-FAST. (us, as an aside, these maps can only be
computed from analyses that were run with a gamma fit paramter). ese values are then transformed into the rescaled values which are by default centeredaround 1000.
view_sm will display a selectivty map from within Matlab. ere are a number

of things that can be done with the selectivity map, such as view a certain slice,
view a mosaic, and view the actual selectivity indices. To get more information,press “h’’ for a help window.

ar g ument s
re quired ar g ument s- a n a l y si s a n a l y si sNa me
Name of a fsfast analysis- pr e f er r e d c ond it ion nu mb er
Condition number for the “preferred’’ condition, i.e., the condition you areinterested in viewing selectivity.
- non - pr e f er r e d c ond it ion nu mb er
Condition number for the “non-preferred’’ condition, i.e., the condition towhich you want to comapre the selectivity of the “preferred’’ condition.
- s f s e s sid f i leName of the session ID file. Note that only one session ID in the file will be
used (the last one)
- d f s e s s d i r f i leName of the session directory file.

optional ar g ument s- f r a c m a s k f r a c t ion
Specifiy a fraction of selectivity indices to show, masking all others. Note thattaking a relatively high fraction, such as 0.8 or 0.9, will not clutter the map, as
most selectivity indices will be clustered in the middle of the curve. e default
is 0.9.
- t y p e s e le c t i v it y i nde x t y p eSpecify a type of selectivity index to compute. ere are currently two indices
implimented, with plans for user-defined indices in the future.
1. (preferred - non-preferred)/(preferred + non-preferred)mannual pages for scripts

67

68

appendix X

2. (preferred - non-preferred)/(hemodynamic offset of the voxel)
e default selectivity index formula is 1.
- r oi m a s k r oi _ n a me
Name of an ROI to use to mask the selectivity indices. If used, only those
selectivity indices that are also in your ROI will be displayed. Note that yourROI directory must follow the normal conventions and must be named with theanalysis given. As well, using the options -frac ,-min , and -max will have noeffect when using -roimask .
- e xc lude
Exclude all selectivity indices that fall outside of two standard deviations fromthe mean. is is only used when using an ROI to mask your selectivity indices.
Be wary of using this, as it throws out data.
- b a s e r u n Di r e c t or ye name of a different base directory on which to overlay the selectivity map,
this defaults to the first run in the bold directory or the first run in your runlist(if you have a runlist defined).
- f u nc d i r b old
e name of the directory holding the functional runs, it is usually called“bold’’ and defaults to “bold’’.
- he lp
Provides complete argument information.
-man
Provides verbose usage information (this document).
- de bu g
Provides useful debugging information.

exampleview_sm -analysis faces -preferred 1 -non-preferred 2 -frac 0.8 -sf sessid -df
sessdirbugs

None known.
If you find any, please send e-mail to < froibugs@sourceforge.net>.

revision$Id: view_sm,v 1.5 2003/08/27 16:04:53 nknouf Exp $mannual pages for scripts

69

indexCL

c ombi n i n g l a b e l s

l i s t i n g ROI s

with combine_label       c ombi n i n g ROI s

with list_roi   log f i le s with combine_roi       c omput i n g ROI r e su lt s
with compute_roi             c r e at i n g a ROIM
m a ppi n g a l a b e l t o a ROI
using label2roi      
m a ppi n g a ROI t o a l a b e lwith make_roi          with roi2label          
 

D

N

de bu g g i n g. S ee log f i le s

n a m i n g of ROI s ER

e d it i n g a ROI

ROI a n a l y si s s t e p s with edit_roi                

ROI b a sic s  F
f r oi I

ROI d at a f or m at ROI n a m i n g. S ee n a m i n g of
ROI s
ROI ov erl a p
creating using combine_roi  
viewing with display_overlap       S

i n s t a l l at ion s av i n g

ROI s .

S ee ROId at a71

72

f or m ats e le c t i v it y m a p s 
creating and viewing    s p at i a l a c t i v it y pr of i le s 
creating and viewing  V
v ie w i n g ROI r e s u lt s
with view_roi_results      