AFNI HOW-TO #1:
BLOCK DESIGNS AND AFNI 3dDelay
Table of Contents:
* Create AFNI datasets using to3d
* Organize EPI runs and create AFNI datasets using Ifile/GERT_Reco
* Register volume data using 3dvolreg
* Average your data using 3dcalc
* Create an ideal reference function using waver
* Analyze time series data using 3ddelay
Fun Extras:
* Strip skull using 3dIntracranial
------------------------------------------------------------------------
------------------------------------------------------------------------
* EXAMPLE EXPERIMENT *
------------------------------------------------------------------------
------------------------------------------------------------------------
The following experiment will serve as our example:
Experiment: Retinotopic, visual stimulation task. A flashing, rotating
hemifield checkerboard appears. Presentation of the hemifield
is separated by a blank screen.
Design: BLOCK
Conditions: 1. Rotating hemifield
2. Blank screen (Rest)
Data Collected: One spoiled grass anatomical scan
(stored in a directory called 'SPGR_data')
Two EPI time-series scans
(stored in a directory called 'EPI_data')
------------------------------------------------------------------------
------------------------------------------------------------------------
* COMMAND: to3d
Use AFNI 'to3d' to convert your anatomical image files into 3D datasets.
'to3d' converts I-files (2D slices) into AFNI .BRIK format (3D volume
datasets).
Usage: to3d [-options] image_files
(see also 'to3d -help')
----------------------------------------------
* EXAMPLE of 'to3d' from the command line:
cd to the directory containing your anatomical I-files (SPGR_data/) and
run 'to3d' from there...
to3d -prefix ARzs_spgr -spgr SPGR_data/I.*
This command will create a head and brick file of your anatomical data.
ARzs_spgr+orig.BRIK
ARzs_spgr+orig.HEAD
----------------------------------------------
* EXAMPLE of 'to3d' from the graphical user interface (GUI):
cd SPGR_data
to3d I.*
An AFNI 'to3d' graphical interface will appear. You can provide auxiliary
information, like voxel size and spatial orientation, by filling out this
on-screen form (if you are converting I-files, this information will
already be filled out by AFNI).
The on-screen form will ask for a prefix for your 3D dataset file. For
this example, our prefix is ARzs_sprg. Once you select a prefix,
SAVE DATASET.
You have now created an AFNI dataset
ARzs_spgr+orig.HEAD
ARzs_spgr+orig.BRIK
Note: 'to3d' is capable of reading other image formats in addition to
I-files (e.g., Mayo ANALYZE .hdr/.img files and Siemens .ima files).
------------------------------------------------------------------------
------------------------------------------------------------------------
* COMMAND: Ifile/GERT_Reco
Want to create an AFNI dataset from your time-series data?
Use AFNI 'Ifile'.
Usage: Ifile [-options] <File List>
(see also 'Ifile -help')
EPI images collected using GE's Real Time (GERT) EPI sequence are saved in
a peculiar fashion. It is often the case that you cannot determine where
one EPI run ends and the other begins.
The 'Ifile' program attempts to identify complete scans from the list of
images supplied on the command line and generates the commands necessary
to turn them into AFNI bricks using the script '@RenamePanga'. If at
least one complete scan is identified, a script called 'GERT_Reco' is
created. Executing it creates the afni bricks that are automatically
placed in a directory called 'afni'.
What is a <File List>? It is a string of wildcards defining series of
GE-Real Time (GERT) images to be assembled as an afni brick (see example
below).
* EXAMPLE of Ifile/GERT_Reco:
cd to the directory containing your time-series I-files (EPI_data) and
run Ifile from there...
cd EPI_data
Ifile -nt '???/I.*'
After '@RenamePanga' has run, a message will appear informing the user of
the number of complete scans that were detected.
E.g., "Found 2 complete scans. Run GERT_Reco to create AFNI bricks."
Now you can run 'GERT_Reco'.
./GERT_Reco
Note: It is not necessary to run both 'Ifile/GERT_Reco' AND 'to3d'.
'GERT_Reco' will automatically call 'to3d' and run it from the
command line.
The output files will appear in the 'EPI_data/afni' directory with the
prefix "OutBrick", followed by the run number (i.e., _r1, _r2,...)
E.g., OutBrik_r1+orig.BRIK OutBrik_r1+orig.HEAD
OutBrik_r2+orig.BRIK OutBrik_r2+orig.HEAD
If you prefer a prefix other than 'OutBrik', you can:
1. Open the GERT_Reco script in a text editor and edit the
'set OutPrefix' line. For our example dataset, we have set the
prefix to ARzs_EPI.
2. or you can you can change the output prefix from the command line:
E.g., sed 's/OutBrick/ARzs_EPI/' GERT_Reco > new_GERT_Reco
tcsh new_GERT_Reco
Now if you run the 'new_GERT_Reco' scripts, which contains the
edited output prefix, the output datasets will contain the
prefix 'ARzs_EPI'.
We have sucessfully created our AFNI datasets!!!
These are the sample datasets we will be using in this tutorial:
3D+time datasets (located in the EPI_data/afni directory):
ARzs_EPI_r1+orig.BRIK ARzs_EPI_r1+orig.HEAD
ARzs_EPI_r2+orig.BRIK ARzs_EPI_r2+orig.HEAD
Anatomical (located in the SPGR_data directory):
ARzs_spgr+orig.BRIK
ARzs_spgr+orig.HEAD
--------------------------------------------
* For clarity, place all of the datasets into ONE directory, for example, the
'afni' directory. Begin by moving the 'afni' directory one level up, and
then transferring the datasets.
mv afni .. (this will move 'afni' to the same level as the
SPGR_data and EPI_data directories. The EPI
datasets are already in here, so all we have to
do is move the SPGR datasets into this directory)
cd ..
mv ARzs_spgr+orig.* afni
Now all our data files are located in one directory. We can now proceed
with registering our data...
-------------------------------------------------------------------------------
-------------------------------------------------------------------------------
* COMMAND: 3dvolreg
Need to volume register your data?
Usage: 3dvolreg -prefix <prefix name> -base <base file> <target file>
(see also '3dvolreg -help')
If you have multiple runs, you will probably want to do a volume
registration on your data, i.e., bring the images you collected with
different methods or different times into alignment.
First, you must select a base image J[x] from which to align the remaining
target images I[x]. Given J[x] and I[x], find a geometric transformation
T(x) so that the difference T(I[x]) - J[x] is minimized (i.e., each image
I[x] is rotated and shifted to lie on top of the base image J[x]).
How do you choose a base image? Your best choice for EPI is one that was
collected very close in time to when the spgr image was collected. In
this example, the sgpr data was collected after the EPI data. And since
there were 2 runs with 160 time points (0 through 159), we have chosen to
register the EPI data to run 2, time point 155.
* EXAMPLE of 3dvolreg:
Base image for our EPI data: ARzs_EPI_r2+orig[155]
(We chose time point #155 rather than the last one in the run (#159)
because times points at the very beginning or very end of the time
series tend to contain more noise.)
cd to the directory containing your time series datasets (afni/), and run
'3dvolreg' for each volume...
cd afni
3dvolreg -prefix ARzs_EPI_r1_vr -base ARzs_EPI_r2+orig'[155]'\
ARzs_EPI_r1+orig
3dvolreg -prefix ARzs_EPI_r2_vr -base ARzs_EPI_r2+orig'[155]'\
ARzs_EPI_r2+orig
Volume Registered datasets we have created:
ARzs_EPI_r1_vr+orig.BRIK ARzs_EPI_r1_vr+orig.HEAD
ARzs_EPI_r2_vr+orig.BRIK ARzs_EPI_r2_vr+orig.HEAD
-------------------------------------------------------------------------------
-------------------------------------------------------------------------------
* COMMAND: 3dcalc
Need to average your datasets?
Usage: 3dcalc [-options]
(see also '3dcalc -help')
The 3dcalc program allows the user to perform arithmetic on 3D datasets,
voxel-by-voxel (no inter-voxel computation).
* EXAMPLE of 3dcalc:
In this example, we will average our two volume registered time series
datasets. cd to the directory containing these datasets...
cd afni/
3dcalc -a ARzs_EPI_r1_vr+orig -b ARzs_EPI_r2_vr+orig \
-expr '(a+b)/2' -prefix ARzs_EPI_avg
-a, -b, ... -z: The voxel values from our sample datasets
ARzs_EPI_r1_vr+orig and ARzs_EPI_r2_vr+orig are labeled
'a' (hence the '-a' option) and 'b' (hence the '-b'
option) respectively. You may use up to 26 datasets
(with voxel values ranging from 'a' to 'z').
Averaged dataset we have created:
ARzs_EPI_avg+orig.BRIK
ARzs_EPI_avg+orig.HEAD
------------------------------------------------------------------------------
------------------------------------------------------------------------------
* An extra tidbit:
In addition to '3dcalc', there are a few other AFNI programs that allow
you to average datasets:
1) @4Daverage
This is a script file that uses 3dcalc to compute average 3D+time
bricks.
Usage: @4Daverage <average 3D+t brick prefix> <3D+t brik names...>
E.g., @4Daverage ARzs_EPI_avg ARzs_EPI_r1_vr+orig ARzs_EPI_r2_vr+orig
E.g., @4Daverage ARzs_EPI_avg ARzs_EPI_r*_vr+orig.HEAD
You can use wildcards if the datasets you want to average have similar
names (as was done in the second example). Be sure to use the .HEAD
suffix, for instance, so that the wildcard will not expand to both the
.HEAD and .BRIK files (and would then use the datasets twice).
2) 3dMean
Usage: 3dMean [-options] <datasets...>
E.g., 3dMean -prefix ARzs_EPI_avg \
ARzs_EPI_r1_vr+orig ARzs_EPI_r2_vr+orig
3) 3dmerge
Usage: 3dmerge [-options] <datasets...>
E.g., 3dmerge -prefix ARzs_EPI_avg -doall \
ARzs_EPI_r1_vr+orig ARzs_EPI_r2_vr+orig
------------------------------------------------------------------------------
------------------------------------------------------------------------------
DATA PRE-PROCESSING IS COMPLETE.
STATISTICAL ANALYSIS TO PRODUCE FUNCTIONAL DATA BRICKS IS NEXT ...
-----------------------------------------------------------------------------
------------------------------------------------------------------------------
* COMMAND: waver
Usage: waver [-options] output_filename
(see also 'waver -help')
The waver program creates an ideal waveform time series file. We will
compare this ideal reference function with the 160 point time series
for each voxel of our averaged dataset.
* EXAMPLE of waver:
waver -GAM -dt 2 -nmount 160 \
-inline 15@0 \
15@1 7@0 15@1 8@0 \
15@1 7@0 15@1 8@0 \
15@1 7@0 15@1 8@0 \
10@0 \
> Ref_ARzs.1D
-GAM = tells waver to use a Gamma variate waveform.
-dt = tells waver to use 2 seconds for the Delta time.
-nmount = specifies that the output will be 160 points in time.
-inline = specifies 'ON' 'OFF' periods for input stimuli.
'0' = OFF and '1' = ON.
'>' = redirects the output into a newly created file that we have
named 'Ref_ARzs.1D.
(see also Unix help for a more in-depth explanation of these
options as they pertain to this example dataset.)
------------------------------------------------------------------------------
------------------------------------------------------------------------------
* COMMAND: 3ddelay
Usage:
3ddelay -input <filename> -ideal_file <ideal time series file name>
-fs <sampling freq in Hz> -T <stim period in seconds>
[-prefix bucket]
(see also '3ddelay -help')
The '3ddelay' program estimates the time delay between each voxel time
series in a 3D+time dataset and a reference time series. The estimated
delays are relative to the reference time series. For example, a delay
of 4 seconds means that the voxel time series is delayed by 4 seconds
with respect to the reference time series.
* Why use 3ddelay with this sample data?
Estimating the response delay of activated voxels is done using the program
3ddelay (or the AFNI plugin Hilbert Delay 98). The program implements a
computationally efficient way of estimating the response delay of each
voxel along with its cross-correlation coefficient which is used to
determine whether a voxel is activated by the stimulus or not. The response
delay is estimated using the Hilbert Transform of the cross correlation
function.
* EXAMPLE of 3ddelay:
3ddelay -input ARzs_EPI_avg+orig
-ideal_file Ref_ARzs.1D
-fs 0.5 -T 45
(see also Unix help for a more in-depth explanation of these
options as they pertain to this example dataset.)
Note: If the '-prefix' is not used (as in the above example), the default
prefix will be the prefix of the input 3D+time brick with a '.DEL'
extension appended to it.
FINALLY, we have a functional dataset!
ARzs_EPI_avg.DEL+orig.BRIK
ARzs_EPI_avg.DEL+orig.HEAD
------------------------------------------------------------------------------
------------------------------------------------------------------------------
** SOME 'FUN' EXTRAS **
------------------------------------------------------------------------------
------------------------------------------------------------------------------
* COMMAND:3dIntracranial
Usage:
3dIntracranial -anat <anat filename> [-options] -prefix <prefix name>
(see also '3dIntracranial -help')
The '3dIntracranial' program performs an automatic segmentation of the
intracranial region (i.e., skull stripping).
* EXAMPLE of 3dIntracranial:
3dIntracranial -anat ARzs_spgr+orig -prefix ARzs_spgr_NoSkl
New dataset we have created:
ARzs_spgrNoSkl+orig.BRIK
ARzs_spgrNoSkl+orig.HEAD
With the skull stripped, this dataset can be viewed in the volume
rendering plugin available in AFNI.
------------------------------------------------------------------------------
------------------------------------------------------------------------------
TIME TO VIEW THE DATA IN AFNI!!!
------------------------------------------------------------------------------
------------------------------------------------------------------------------
Now that the data have been processed and analyzed, they can be viewed in
AFNI. Below are some recommendations for displaying and the viewing the
data:
cd to the directory conatining the datasets and run AFNI from there ...
cd afni/ (Note: our data is contained in the 'afni' directory
we created earlier)
afni (Note: once we descend into the 'afni' directory,
typing 'afni' on the command line will launch
the AFNI program.)
The main AFNI window will appear.
SWITCH ANATOMY: Click on this button to choose an anatomical 3D datset to
view. In this example, select the dataset 'ARzs_spgr.'
Press the "SET" button to continue.
To view this dataset, click on the AXIAL, SAGITTAL, and
CORONAL buttons that appear on the main AFNI window.
At this point, there should be no fucntional data
overlaid onto these anatomical images.
DEFINE FUNCTION: Click on this button to begin the process of
overlaying the functional data onto the anatomy. Once
this button is selected, another control panel, with
additional options, will appear to the right of the
main AFNI window.
Note that function will not be seen overlaid onto the
anatomical images until the SEE FUNCTION box, which
appears below "DEFINE FUNCTION", is highlighted.
(A) SELECT FUNCTION AND THRESHOLD:
The first step (within the "DEFINE FUNCTION" control panel) is
to select the sub-brick you would like to view (click on the
'Func' button), and the sub-brick with which to threshold
(click on the 'Thr' button).
For this example, we can view functional activity that results
from the delay and set the threshold based on the correlation
coefficient. To do this, go to the 'Func' button and select
the "Delay" sub-brick (#0). Set the threshold by clicking on
the 'Thr' button and selecting the "Correlation Coefficient"
sub-brick (#2).
(B) SET THE THRESHOLD SLIDER BAR
To the left of the 'Func' and 'Thr' buttons is a slider bar
that is used to adjust the threshold for function display.
Since the threshold ranges from -0.074 to 0.922, be sure the
button below the slider bar (with the two asterisks to the left
of it) is set to "0" (this should be the default). The "0"
signifies that the range of the slider bar is from .0000 to
.9999.
One way to select an appropriate threshold for function display
is to drag the slider bar until there are no (or very few)
extra-cranial colored voxels. For this example, set the
threshold bar to about .4362, which sets the p-value to 7.1-8
(i.e., 7.1 times 10 to the power of -8). This is the
significance value PER VOXEL.
(C) CHANGE THE NUMBER OF COLOR PANES
Next to the threshold bar is a color pane. The default is set
at 9 colors, but this can be adjusted by clicking on the button
right below the color panes. For this example, change the
color spectrum to 20.
(D) ADJUST THE RANGE OF VOXEL INTENSITIES
For this example, the voxel intensity ranges from 0 to 118.8217.
However, there are probably very few voxels in the high range,
near 118. We know from viewing our data that most voxels do
not reach an intensity greater than 40. However, the
'autoRange' button that appears to the right of the color bar
is highlighted by default and set to 118.8217. Setting such a
wide range of voxel intensities does not allow us to make good
use of the color bar, since most voxels will not fall in the
high intensity range. Therefore, our functional overlay will
look somewhat monochromatic because so few voxels are assigned
a high intensity color value. To remedy this problem,
de-select the 'autoRange' button and set the range (in the
space below) to 40. By doing this, we make better use of the
color bar.
(E) CHECK FOR NEGATIVE FUNCTION VALUES
In this example, our function values range from 0 to 118.8217.
As such, we have no negative function values. If this is the
case, it is best to highlight the "Pos?" button that appears
below the color bar. Doing so allows us to make better use of
the color spectrum available on the color bar because none of
the colors are representing negative function values (which are
nonexistent in our example).
(F) MAKE YOUR FUNCTIONAL DATA LOOK PRETTY
As it is now, the functional data looks a bit blocky. To
improve its appearance (and make it worthy of publication),
go to DEFINE DATAMODE. This will open up a window. To the
direct right of "DEFINE DATAMODE" you will see two buttons:
"Func resam mode" and "Thr resam mode". These buttons allow
you to resample your functional data. For this example, select
CUBIC interpolation for both buttons. Doing this will give
your functional overlay a smoother, less-blocky, appearance.
THAT'S ALL THERE IS TO IT!!! For fun, rotate the colors on the color bar
by clicking on the "Rota" up and down arrows (which appear right below the
"autoRange" button in the Define Function control panel). Doing so allows
you to view the effect of the delay on functional activity.
-------------------------------------------------------------------------------
-------------------------------------------------------------------------------
CONGRATULATIONS,
YOU HAVE COMPLETED THE FIRST HOW-TO !!!
-------------------------------------------------------------------------------
-------------------------------------------------------------------------------
There is a tremendous amount of information in this how-to, which may seem
overwhelming at first. However, all it takes is some time and practice to
master the art and science of FMRI analysis.
For additional information on AFNI, FMRI, and statistical principles and
concepts, see the EDUCATIONAL MATERIAL ON THE AFNI WEBSITE:
AFNI educational material
Also feel free to view the message boards and to post a question yourself:
AFNI message board