---

Q1. What does the word AFNI mean?
AFNI stands for Analysis of Functional NeuroImages. I chose this name because it was easy to vocalize and wasn't a word (at least in English - I've heard that it is a woman's name in some Moslem countries); in particular, I didn't want to name the software "Brain Whatzis" for any value of "Whatzis".

An alternative definition of AFNI can be found at this page.

AFNI refers to both the entire software package (comprising dozens of program and plugins), and also to the specific program of that name. The situation is confusing, but that's the way it is.

The name starts with the letter "A", which means that AFNI almost always appears first on any list of FMRI software packages. This is as it should be, of course, but was not intentional in any way.

Why AFNI is Free
I am often asked why I chose to give AFNI away, rather than sell it, or keep it as in-house software for MCW use alone. Frankly, I don't want the support hassles that would be incurred with commercialization - right now, your only support option is to hope that I will answer your e-mail (or message board posting) before the innermost circle of hell thaws out. As to keeping it proprietary, I've benefited greatly from code and other things that people have put on the Internet, and so felt like giving something back.

Asking For Help
If you do send me e-mail about a problem, please realize that there are well over 100,000 lines of code in the package - not counting stuff taken off the Internet, such as the cdf and volpack packages - and that I don't keep all the details in my head (I have to save most of my synapses for Star Trek and Tolkien info). This means that you should send me a detailed description of what you did, including a copy of the command line, if you were running a batch program, any error messages from the program, and some information about the datasets you input (e.g., the output of 3dinfo). Just saying "I tried this and it didn't work. What's wrong?" won't usually be enough.

With the AFNI package, I provide you with some of the tools needed to analyze FMRI data. This does not mean that I am an expert on analysis of your particular data. I probably can't advise you on what is the proper set of tools to apply. Questions that there are no authoritative answers to include

• Should I blur my results before intersubject averaging (or other analysis)? How much?
• What are the best values for the clustering parameters rmm and vmul (cf. Q24)?
• Should I average time series and then analyze, or analyze first and average later?
• I don't see any subject motion; should I register images anyway?
• Which is better: correlation analysis, ICA, or fuzzy clustering?
• Which is better: AFNI, MedX, or SPM?
• Is there an infinite set with cardinality between that of the natural numbers and that of the continuum?

There is a phrase in the MIT X11 documentation that summarizes the philosophy behind the AFNI toolkit: Provide mechanism, not policy

FMRI Courses
The Medical College of Wisconsin offers a 3-day course on "How to do FMRI", including a 1 day introduction to the use of AFNI. More information can be found here. This course can get you going in FMRI data gathering and analysis - it is not really appropriate for those who already have extensive FMRI experience.

The MGH NMR center also offers a short course on FMRI; information about this course can be found here.

Some educational materials about AFNI and FMRI in general can be found on this web site here.

AFNI Version Numbers
Version numbers are assigned by whim. The first version distributed outside of MCW was 1.10, released in Feb 1995. Version 2.00 was the upgrade from 3D to 3D+time datasets (which involved a lot of internal changes). Since then, the version number has only crept upwards, since no vast changes to the package have been made - only incremental additions, mainly in the form of new "3d*" command-line programs and new plugins. You can check your version of AFNI by running the command line program afni_vcheck, or by using the Define Datamode->Misc->Version Check menu item in the interactive AFNI program.

Referencing AFNI:
If you wish to refer to AFNI in a publication, then the proper reference is

RW Cox.
AFNI: Software for analysis and visualization of functional magnetic resonance neuroimages.
Computers and Biomedical Research, 29: 162-173, 1996.

Here is a PostScript preprint [650 K] of this article. Here is a list of articles that refer to AFNI.

[Answer last changed 12 Nov 2001]

---

Q2. When will you port AFNI to Windows?
When there is enough incentive. At present, my incentive level is for this is at -314. It will have to be positive before any action is taken. (Units are winning PowerBall tickets.)

If you are interested in a port to Windows 95/97/98/NT/2000/ME/XP, please explain - in copious detail - why I should do it.

[13 Sep 2001]: On the other hand, I've now gotten AFNI to work on Mac OS X. The details can be found here.

In principle, porting to Windows could be done using the Cygwin tools. This seems like such a large job that I'm loathe to undertake it.

[08 Jan 2002]: Look here for further information.

---

Q3. What to do if AFNI crashes?
Please try to duplicate the situation that creates the error. If possible, run AFNI with the "-TRACE" option so that it will tell where it is in the code when it dies. Then send me (rwcox@nih.gov) e-mail with the description of the problem and the output of "afni -TRACE". You may be asked to provide data files (e.g., BRIK and HEAD files) as well.
(N.B.: This internal tracing is disabled on the Solaris versions of AFNI, since it causes problems there for unknown reasons.)

An alternative to "-TRACE" is to start AFNI using the GNU debugger, run it to the crash point, then print out the stack trace:

  gdb afni
  > run
    ... do stuff until it crashes ...
  > backtrace
  > quit 

This will help localize the problem, and may make it possible to figure out what is going on.

Plugin problems:
Sometimes a problem occurs when you have multiple installations of AFNI in your path. If this occurs, and you don't have the environment variable AFNI_PLUGINPATH, then the plugin startup code searches all directories in your path for plugins. If there is an older version of AFNI somewhere in the path, then its plugins will be loaded. However, an older plugin may not be compatible with newer AFNIs, and then the plugin's startup code may crash the whole program.

The solution to this plugin problem is to set correctly AFNI_PLUGINPATH. The procedure for doing this is described in Q53.

Memory problems (the computer's, not yours):
On some Linux systems, AFNI programs can fail with an error message saying that "malloc failed" or "out of memory", even when there is a lot of memory left on the system. This seems to be due to a bad interaction between the Linux C library's malloc() and mmap() functions when allocating large chunks of memory (100+ Mbytes).

The solution to this problem is to set the environment variable AFNI_NOMMAP to YES; this can be done in your .cshrc, .profile, or .afnirc file, as appropriate for your configuration. See README.environment for more details on AFNI environment variables and how to set their values.

[Answer last changed 12 Nov 2001]

---

Q4. Can I use AFNI on a 24-bit X-Server?
A number of people are using PCs running some version of Windows (NT, 95, 98, Catalan's constant, or whatever version Bill is at now) to display AFNI running on a remote Unix box. Most of these servers are set up to run in 24 bit TrueColor mode. AFNI now works with this type of display, but you must be up-to-date (version 2.20, at least). One advantage of using TrueColor is that the image viewing windows now allow you set the overall to be translucent, so you can see through the overlay to the underlying anatomical image.

AFNI will work with 4-15 bit PseudoColor X11 visuals and 8-32 bit TrueColor visuals. It will not work with the StaticColor or DirectColor visual types, but these are fairly rare. The older program FD2 has not been refitted to use TrueColor, and so will only run if the default X11 visual is of PseudoColor type.
[16 Oct 2001]: FD2 now works with TrueColor, thanks to Andrzej Jesmanowicz of MCW.

Some of the colormap control functions (at the right edge of the image display windows) behave a little differently under TrueColor than they do under PseudoColor.

Nota Bene [19 Apr 2000]:
I have recently discovered that when your X11 server is set to 16 bit TrueColor mode, then the colors displayed on the screen may not be exactly what you requested. There is no visual difference, but gray values are not exactly gray. My guess is this happens when the server uses 5 bits for Red and Blue, and 6 for Green (the very common 565 configuration, used because human vision is more sensitive to Green). Then the colors actually displayed are computed from the colors requested with different accuracy in G than in RB, so the results are slightly different.

This caused a problem for us when doing Save:pnm, since that makes an exact copy of what is shown on the screen (before stretching the image to match the window, that is). The result was that an image that was supposed to be grayscale was not - the G values were 1 or 2 off from the RB values (a gray pixel should have R=G=B).

I don't know of an AFNI solution. The solution for us was to set the Linux PCs here to run in 24 bit TrueColor mode. This has 8 bits of color accuracy per pixel, so if R=G=B on input, then R=G=B on output.

• If you are using the XFree86 X11 server on Linux, you need to modify your XF86Config file - this can be done by manually editing the file, or by using the XF86Setup program.
• If you are using the Accelerated X server on Linux, the Xsetup program can be used to alter the server configuration.
• If you are using an SGI workstation, see the next question.

Changing the X server configuration requires super-duper-user (root) access.

---

Q5. I've run out of colors. What to do?
A message like

  ** XAllocColorCells fails for 75 colors
  ** try the -ncolor option to reduce # of colors

when you try to start AFNI means that the program can't allocate enough color cells from the 8 bit PseudoColor colormap. Reasons this might occur are:

• You are running some other big color hog, such as Netscape or other imaging program.
• You are using a window manager (such as CDE) that uses a lot of colors for fancy decorations.

Possible solutions are to

1. Kill the color hog(s) so you can run AFNI first; and/or
2. Setup the window manager to use less colors; and/or
3. Run AFNI with the "-install" command line option; and/or
4. Switch your X11 setup to be 24 bit TrueColor or 12 bit PseudoColor.
   The latter option is only possible on SGI systems, as far as I know. On our IRIX 6.2 systems, the file /var/X11/xdm/Xservers is the place where you can set the SGI X11 server to start up in 12 bit mode, if that is supported on your machine (I don't think it is supported on the Indy). I have set this file to be

     :0 secure /usr/bin/X11/X -bs -nobitscale -c -pseudomap 4sight \
       -solidroot sgilightblue -cursorFG red -cursorBG white -depth 12
   

   This is all one line. I have just added the option "-depth 12" to the default setup shipped by SGI. If you try this, be sure to save a copy of the original file, in case it doesn't work. After you change /var/X11/xdm/Xservers, you will have to reboot the system (or otherwise force the X11 server to restart).

   If you want to change the SGI X11 server to start in 24 bit TrueColor mode, instead of adding "-depth 12" to the command line above, add "-class TrueColor -depth 24".

5. If you are using Linux, need to reconfigure your X11 server and are using XFree86, this can be done with the program xf86config, or with some programs that come with various Linux distributions (e.g., Xconfigurator from RedHat).

---

Q6. I clicked in the wrong place in an image. How do I go back?
Although it is in the AFNI manual (afni200.ps, page 18), not many users seem to know that there is a right-click popup menu attached to each image window. The most useful item is "Jumpback", which will reposition the (x,y,z) location of the cursor to its previous position. This is useful for those that sometimes click in a stupid place (not you, of course, but that bozo down the hall you have to explain these things to).

---

Q7. How do I hide the controls in an image display window?
On the same right-click popup menu, the "Image Display" option will hide the controls for the image window, and just leave the image itself on display. Choosing this item again will bring the controls back to visibility.

---

Q8. How do I control the grayscale in an image window?
Normally, each slice is displayed with its intensity-to-grayscale (I->G) map chosen to make that particular image look decent. Displaying a new slice will result in a new I->G map being used. (This is also true in a Montage--each slice shown will have its own I->G map.) There is an undocumented way to make the I->G map fixed for a given image viewing window. Its usage is a little clumsy:

1. Right click in the intensity scale bar just to the right of the image window. This will popup a hidden menu.
2. Pick the item "Choose Display Range".
3. This gives a control window with the instructions

     Display range: bot top [ztop]
   

   In this window, type the intensity value you want mapped to the darkest level (bot), a space, and the intensity value you want mapped to the brightest level (top). You might choose these values from the scales shown just below the image slider, but you will probably need to experiment. Then press the "Apply" button.
4. From this point, the slices displayed in this window will bypass the normal scaling and be mapped linearly from bot->darkest to top->brightest. Values below bot also map to darkest, values above top also map to brightest. If you type a " 1" after the value of top, this is a flag to display values above top as dark instead of bright. In this way you can try to display only gray matter, say.
5. To restore normal processing of the I->G map, you must enter bot and top both as zero, then press "Apply" (or "Set"). Note that if you close the image window (with the "Done" button), then reopen it, you get a new set of interface widgets that do not remember the settings you made previously.

---

Q9. How do I choose the color displayed for zero image intensity?
From the same intensity scale bar hidden menu, the item "Choose Zero Color" pops up a color menu that lets you select the color that the background dataset value of zero will be displayed as. In conjunction with the "ztop" feature of the above item, you can make some pretty bizarre looking images. Utility, of course, is in the eye of the beholder. (I can't remember now why I put this in the code, but I had some use for it, once upon a time.)

---

Q10. Are there any "fun" features in AFNI?
I thought you'd never ask. Clicking any mouse button in the blank space to the right of the "Done" button in an AFNI controller window has various amusing--some say terrifying--consequences (one for each button).

---

Q11. How can I see the numerical value stored in a voxel?
A label showing the values of the current Anatomy, Function, and Threshold dataset bricks at the crosshair point is at the bottom of the rightmost column in the "Define Function" control panel. This label is only active when all three viewing windows are open at once. (This is due to the way that AFNI accesses data bricks.) If you want to see the voxel values, but don't want to see all the image windows, open all the image windows anyway and just iconify (minimize) the ones you don't care about.

---

Q12. How do I read images from format "X"?
to3d and other programs that read images (not AFNI datasets) can read image data from almost any uncompressed file format, including data stored in big 3D and 4D files. These methods are described on pages 63-64 and 72-74 of the auxiliary programs manual (afni_aux.ps), or in the output of "to3d -help". A summary is given here.

Image files may be single images of unsigned bytes or signed shorts (64x64, 128x128, 256x256, 512x512, or 1024x1024) or may be grouped images (that is, 3- or 4-dimensional blocks of data). When entering data that is not in the pre-recognized formats, the onus is on the user to specify the location of the image data in the file. This is done with the following type of file specification:

 3D:hglobal:himage:nx:ny:nz:fname   [16 bit input]
 3Ds:hglobal:himage:nx:ny:nz:fname  [16 bit input, swapped bytes]
 3Db:hglobal:himage:nx:ny:nz:fname  [ 8 bit input]
 3Di:hglobal:himage:nx:ny:nz:fname  [32 bit input]
 3Df:hglobal:himage:nx:ny:nz:fname  [floating point input]
 3Dc:hglobal:himage:nx:ny:nz:fname  [complex input]

The elements of this complicated string are:

• The "3D" prefix, where
  • "3D:" signals that the image data are signed shorts (16 bit integers).
  • "3Ds:" signals that the image data are signed shorts that should be byte-swapped as they are read in.
  • "3Db:" signals that the image data are unsigned bytes (8 bit integers).
  • "3Di:" signals that the image data are signed ints (32 bit integers). Note that AFNI itself cannot deal with int datasets.
  • "3Df:" signals that the image data are 32 bit floats.
  • "3Dc:" signals that the image data are 64 bit complex numbers (real and imaginary pairs of floats).
• "hglobal" = the global header offset, which is the number of bytes to skip at start of whole file.
• "himage" = the per image header offset, which is the number of bytes to skip at start of each 2D image.
• "nx" = x dimension of each 2D image in the file.
• "ny" = y dimension of each 2D image in the file.
• "nz" = number of 2D images in the file. You can input a single image using nz=1.
• "fname" = actual filename on disk to read.

  Further points about this file format specifier:

• The ":" separators between the elements are required.
• The k-th 2D image starts at BYTE offset into the file of hglobal+(k+1)*himage+vs*k*nx*ny in file "fname" for k=0,1,...,nz-1, where vs=voxel length=1 for bytes, 2 for shorts, 4 for ints and floats, and 8 for complex numbers.
• As a special case, using hglobal=-1 means to read data starting at offset len-nz*(vs*nx*ny+himage), where len=file size in bytes. That is, the image data will be read from as far into the file as possible. This is useful when you don't know the image header size, but do know that there is no "footer" at the end of the file.
• It is now legal to have hglobal<-1, as long as hglobal+himage>=0. This is to allow for the possibility of image "footers". [Requested by Gary Strangman of MGH; implemented 13 Apr 1999.]
• Note that there is no provision for skips between data rows inside a 2D slice, only for skips between 2D slice images.
• The int, float, and complex formats presume that the data in the image file are in the 'native' format for this CPU; that is, there is no provision for data conversion (unlike the 3Ds: format).
• Programs 2swap and 4swap can be used to swap bytes (2 at a time or 4 at a time) on arbitrary files, if necessary when transferring data between CPU types (e.g., MIPS to Intel).
  • The to3d command line options -2swap and -4swap can be used to have the same effect on each input image file, as they are read into memory.
    
  • The Byte Swap button in the interactive to3d control panel can also be used to swap the bytes in a dataset. Combined with the View Images button, this feature lets you visually inspect the images prior to output into the dataset .BRIK file.
    
  • Generally speaking, images you input from the scanner will be non-negative. (Most image reconstruction programs take the absolute value of the reconstructed data as the last step in the process.) If there are negative values in such images, this means that the data is probably byte-swapped relative to the CPU on which you are using to3d. Negative values can and do occur in derived images (e.g., correlation coefficient maps).
• Whether the 2D image data is interpreted by to3d as a 3D block or a 3D+time block depends on the rest of the command line parameters. The various 3D: input formats are just ways of inputting one or more 2D slices from a single file.
• to3d and AFNI incorporate POSIX filename "globbing", which means that you can input filenames using wildcards, and then the programs will internally do the expansion to the list of files. This is only desirable because some systems (e.g., SGI IRIX) limit the number of command-line arguments to a program. (Normally, the shell program to which you type input commands expands wildcard characters such as "*" and "?" to match filenames, and passes the list of matching filenames to the program. If the number of matching filenames is too large, the shell might give an error message and fail to run the program.) It is possible that you would wish to input more slice files than your computer supports. For example,

    >   to3d exp.?.*
  

  might overflow the system command line limitations. The way to do this using internal globbing would be

    >   to3d 'exp.?.*'
  

  where the ' characters are needed so that the shell program doesn't try to expand the wildcard characters "?" and "*" itself.
• Internal globbing of the "3D:" type of file specifiers is also supported in to3d and AFNI. For example, '3D:-1:0:64:64:100:sl.\*' could be used to input a series of 64x64x100 files with names sl.01, sl.02 ....

Once you understand the "3D:" type of input specifiers, you can set up your Unix environment to recognize certain file lengths as corresponding to a given image format. For example (using C shell syntax)

  setenv AFNI_IMSIZE_1 8272=3D:-1:0:64:64:1:

means that a file containing 8272 bytes will have the string "3D:-1:0:64:64:1:" attached to it before being read by the image input routines. In this case, this would correspond to a single 64x64 image of shorts, with an 80 byte header to be skipped (8272-64*64*2). Once this is set up, all the AFNI package programs that read image files will automatically recognize a file of this length, with no further need to explicitly use the "3D:" specifier on the command line.

The following shows how you can specify a variable length for such automatic recognition:

  setenv AFNI_IMSIZE_2 %16096+80=3D:80:7904:64:64:

The "%" that starts the environment variable is a signal that this is a variable length file type that can contain more than one image. The number of images is determined from the actual file length when it is read. In this example, if the file length is of the form 16096*N+80 bytes, for N an integer, then the string "3D:80:7904:64:64:N" will be put before the filename. This example allows the input of a file that has an 80 byte global header, plus a 7904 byte header per image.

Finally, the preset file sizes that the AFNI package functions recognize are listed below. In the cases with Signa headers, the header information is skipped at the front of the file (AFNI programs do not attempt to read any header information from any scanner manufacturer files). If you create an AFNI_IMSIZE_xx variable with one of these lengths, it will override the interpretation given below. (xx may range from 1 to 99.)

  4096    = 64x64 byte
  8192    = 64x64 short
  16096   = 64x64 short with GE Signa 5.x header
  16384   = 128x128 byte
  32768   = 128x128 short
  40672   = 128x128 short with GE Signa 5.x header
  65536   = 256x256 byte
  131072  = 256x256 short
  138976  = 256x256 short with GE Signa 5.x header
  145408  = 256x256 short with GE Signa 4.x header
  262144  = 512x512 byte
  524288  = 512x512 short
  1048576 = 1024x1024 byte
  2097152 = 1024x1024 short

More finally, complete information about AFNI environment variables can be found in file README.environment.

[14 Sep 1999] Even more finally, to3d now checks float and complex input files for illegal values. See the answer to Q53 for more information.

[10 Feb 2000] Also see Q63.

[09 May 2000] Also see Q66.
In there, the issue of breaking up a set of images that have been assembled into a 2D layout is addressed (using the new program imcutup). The 3D: method can only deal with images that are assembled into a 1D layout, so that all the data bytes for one image are contiguous in the file.

[20 Mar 2001] to3d can now read Mayo ANALYZE75 files (.hdr/.img pairs; see Q13), and also makes an attempt to read Siemens Vision .ima files (which can be arranged into a 2D montage of sub-images, as described in the link immediately above). To input an ANALYZE .hdr/.img pair to to3d, specify the .hdr filename on the command line, as in

  to3d -time:zt 18 160 3s alt+z fred*.hdr

Don't put the .img filenames on the command line!

To input a Siemens Vision .ima file (which contains its own header data), just put the filename on the command line, as in

  to3d -time:zt 7 33 4s alt+z elvis*.ima

[30 Nov 2001] AFNI programs can now read MINC files directly as datasets, without the need to go through to3d. Also, the new program 3dMINCtoAFNI can convert a MINC file to an AFNI dataset; 3dAFNItoMINC will convert an AFNI dataset to a MINC file. (Don't input MINC files to to3d!)

[04 Dec 2001] to3d can now read GE I.* formatted ("ximg"/"IMGF") image files, extracting the voxel sizes, orientations, and offset from the header of each file, as well as determining if the image data in the file needs to be byte-swapped. For example:

  to3d -time:zt 18 100 0s alt+z I.*

will read the 1800 image files I.0001, I.0002, ... I.1800 into a 3D+time dataset. The dataset grid orientation, size, and offset, and the TR should all be read correctly from the headers of the input files. The only thing left for you to supply is the dataset prefix (I hope).
(N.B.: At present, this is the only image format from which TR is read, so it is legal to supply TR=0 in the -time:zt option. For all other image formats, you have to supply a positive TR, or the program will arbitrarily set TR=1s for you.)

[Answer last changed 04 Dec 2001]

---

Q13. Yes, but what about Mayo ANALYZE, or Matlab?
Mike Beauchamp of the NIMH has written the following potentially useful documents:

• How to make AFNI and Mayo ANALYZE interoperate.
• How to use AFNI datasets in a Matlab program.
• A more recent description of using AFNI datasets in Matlab [Ziad Saad].
• How to use program 3dDeconvolve to analyze an FMRI time series with multiple linear regression.

In addition, to3d can now read ANALYZE .hdr/.img file pairs without special 3D: encoding (see the bottom part of Q12, above). Since MRI data in ANALYZE format seems mostly to be stored in 3D arrays, you will generally have a lot of file pairs for an EPI run. You have to use -time:zt to specify the time axis. ANALYZE .hdr files contain the voxel spacings, so you shouldn't have to change those parameters. However, ANALYZE .hdr files do not reliably contain the image orientation or spatial offset, so you have to enter this information manually into to3d.

The new [29 Nov 2001] program 3dAFNItoANALYZE will write the write each 3D sub-brick from an AFNI dataset to an ANALYZE file pair. This capability should make it not-too-painful to use AFNI and SPM together.

[Answer last changed 30 Nov 2001]

---

Q14. to3d and other programs can't read legal image files. What gives?
Program to3d and other image handling programs (e.g., imstat) cannot read image filenames that start with the characters "3D". This is due to the code that interprets such a filename as being a special indicator of 3D stacks of images rather than single images.

---

Q15. I want to input some 8 bit images. How?
to3d will recognize 8 bit grayscale images stored in the raw PGM format, and assemble them into a byte-value AFNI dataset, or convert them into a short-valued dataset (using the -datum command line option). You can use the netpbm utilities (available at the AFNI distribution sites), or the program xv (available here) to convert images of many different types (e.g., TIFF) to the PGM format. This makes it possible to assemble 3D (or 3D+time) grayscale datasets from modalities other than MRI (e.g., digitized photographs).

The AFNI program mritopgm will read a single 2D image in one of the formats described above and convert it to to the raw PGM format. This can be useful for incorporating 16 bit MR images into other documents that require 8 bit files; for example

  mritopgm im.1.08 | pnmtotiff > im.tif

will produce a TIFF image from a 2D MRI slice.

There is no provision at present for colored 3D datasets in the AFNI package.

---

Q16. My anatomical and functional data are oblique!?
AFNI requires that the datasets be on "parallel grids" - that is, that the 2D slices be parallel or perpendicular. Some sites (not MCW) gather functional data that is oblique to the anatomical scans. It is then necessary to rotate one or the other so that their grids are parallel. It is better to rotate the anatomical data, for two reasons:

• It is usually of higher resolution, so will be less affected by interpolation artifacts.
• You usually care more about the functional data, so it should be left alone.

After assembly with to3d, 3D datasets can be rotated using the program 3drotate. Before assembly, 2D images can be rotated using the program imrotate.

---

Q17. What functions are used in program waver?
There is no documentation or publication describing the "Cox" (or -WAV default) waveform generated by program waver. The formula for the impulse response function is as follows:

for t in (-infinity .. delaytime)
  waver = 0

for t in (delaytime .. delaytime+risetime)
  waver = peak * z( (t-delaytime)/risetime )

for t in (delaytime+risetime .. delaytime+risetime+falltime)
  waver = (1+undershoot) * peak * z( (delaytime+risetime+falltime-t) / falltime ) - undershoot

for t in (delaytime+risetime+falltime .. delaytime+risetime+falltime+restoretime)
  waver = -undershoot * peak * z( (delaytime+risetime+falltime+restoretime-t) / restoretime )


for t in (delaytime+risetime+falltime+restoretime .. infinity)
  waver = 0

This is pretty straightforward, allowing the user to control the time breakpoints of the function: delay part, rise part, fall part (including a post-undershoot), and a restoration part (from the undershoot).

The function z(x) above is a function that rises smoothly from z=0 for x<0 to z=1 for x>1. In waver.c, this function is programmed as

for x in (-infinity .. 0 )
  z = 0

for x in ( 0 .. 1 )
  z = 0.50212657 * ( tanh(tan(0.5*PI * (1.6*x-0.8))) + 0.99576486 )

for x in ( 1 .. infinity )
  z = 1

The peculiar looking formula for the meaty part of z(x) was chosen partly by trial and error graphing, and partly because I think that the combination tanh(tan()) is a cool function. It looks OK, and there really isn't enough data to distinguish between different types of curves that make this 0->1 transition used to model the rise and fall of the BOLD response. The graph below shows z(x) for x between -0.5 and 1.5.

The -GAM gamma variate waveform option is derived from Mark Cohen's work (NeuroImage 6:93-103, 1997). Here is a comparison plot:

The -WAV and -GAM data for this graph were produced with the commands

  waver -dt 0.25 -xyout -inline 1 20@0 -undershoot 0 -delay 1 -rise 4 -fall 5
  waver -dt 0.25 -xyout -inline 1 20@0 -GAM

The actual graph was produced with program xmgr, available here.

If you use the gamma variate waveform t**b * exp(-t/c), note that the time-to-peak is b*c and the FWHM of the peak is approximately 2.4 * sqrt(b) * c (the approximation is valid for b > 1). Mark Cohen's values are b = 8.6 and c = 0.547, giving time-to-peak = 4.7 s and FWHM = 3.8 s.

---

Q18. How do I transport image data to a system with swapped bytes?
AFNI datasets created with versions 2.11 and later contain a flag in the .HEAD file that indicates the byte order of the data stored in the .BRIK file. When the dataset is loaded, if it consists of 2 byte shorts, it will be swapped if the CPU byte order differs from the file byte order.

For older datasets, you can go back and attach the header flag about the correct byte order with a Unix shell command of the form

  find /top/dir -name \*.HEAD -exec 3drefit -byteorder NATIVE_ORDER {} \;

where /top/dir is the top of the directory hierarchy that contains all your AFNI datasets.

Image data files themselves (e.g., scanner output) do not contain any information about the byte order of their data. If you do not know what the byte order of a set of image files is, try looking at them (with afni -im or with to3d). Images from the scanner will usually be non-negative. (Most image reconstruction programs take the absolute value of the reconstructed data as the last step in the process.) If there are negative values in such images, this means that the data is probably byte-swapped relative to the CPU on which you are using to3d. Negative values can and do occur in derived images (e.g., correlation coefficient maps).

You can manually byte swap image data files (including .BRIK files) using the programs 2swap (in pairs: ab->ba) and 4swap (in quads: abcd->dcba). Do NOT apply these programs to the .HEAD files! Also, if you byte swap a .BRIK file and the .HEAD file does contain a byte order flag, then you must fix the .HEAD file using the 3drefit command. Otherwise, AFNI will treat your data incorrectly, since you changed the actual byte order but not the byte order flag.

The program byteorder will print out the byte ordering used by the CPU on which it is run. The possible outputs are

• LSB_FIRST = Least Significant Byte first (Intel computers):
  If computers were decimal instead of binary, the number "ninety three" would be stored as "39".
• MSB_FIRST = Most Significant Byte first (most RISC processors):
  If computers were decimal instead of binary, the number "ninety three" would be stored as "93".

The program 24swap can do byte pair and byte tetrad swapping on the same file; for example, it can do a 4swap on the first 1000 bytes of a file, and then a 2swap on the remaining bytes. This can be useful when dealing with image files that have 4 byte headers and 2 byte data.

[20 Sep 1999] AFNI programs now check input datasets to see if they have the byte order flag. If not, a warning message like this will be sent to the terminal:

  *** Dataset r1:time+orig.HEAD: assuming byteorder MSB_FIRST

This warning can be suppressed; see README.environment. All datasets created by versions of AFNI since May 1998 should contain the byte order flag.

Q12 contains a discussion of methods for byte-swapping image files before or during input to to3d.

If you wish to force all newly created AFNI datasets to be stored in a particular byte order, you can do so using the environment variable AFNI_BYTEORDER. Note that when reading in datasets that are byte-swapped relative to the CPU native order, AFNI programs must use malloc() to allocate memory. If the dataset is stored in the CPU native order, then mmap() can be used to directly map the .BRIK file into memory. This can save system swap space, which might be a consideration when using the AFNI package on computers with a tiny amount of RAM (less than 256 MB, say).

[19 Jan 2000] When the input images are shorts, to3d now checks if any of the values are negative. If there are negative voxel values, it displays a warning message. This is intended to help remind you to check to see if the images might need to be byte-swapped.

[Answer last changed 19 Jan 2000]

---

Q19. Are there any man pages for AFNI programs?
No. The closest thing is that most programs take the command line switch "-help", which will print out some information on the usage. We try to keep this information up-to-date (unlike the manuals, which are updated on a time-available basis, which means hardly ever).

For larger scale issues that aren't covered in the manuals, there are also the myriad README.* files, and, of course, this FAQ list.

---

Q20. Show me the Anterior and Posterior commissures!

OK, here they are.

---

Q21. The grayscale image display of my dataset doesn't seem right.
The default mapping from image voxel values to grayscale values is to compute the histogram of the displayed slice, then map the 2% point on the cumulative distribution to the lowest grayscale and the 98% point to the highest grayscale. Intermediate voxel values are mapped linearly to the intermediate grayscale levels in the colormap. This technique of clipping off the smallest and largest values works well for MRI data, which are often plagued by a few bright spots caused by arterial inflow artifacts.

You can switch to map the smallest slice value to the lowest grayscale and the largest slice value to the highest grayscale using the "Disp" control panel in the image window: just select the "Min-to-Max" switch. This is probably a good idea when you are viewing a mask image or other artificially generated data.

When you are making a montage, whichever mode you use is applied to each slice separately and the final montage is pasted together from the results. If you want to control the scaling from voxel values to grayscales so that all slices are treated equally, see the answer to Q8.

---

Q22. How do I control the overlay colors?
Overlay colors are determined by the "Function" dataset. The threshold slider on the "Define Function" control panel interacts with the threshold data brick from that dataset to determine which voxels will be cut off and not be overlaid in color. You can use the "**" control below the threshold slider to control its range, in powers of 10. If the threshold data brick has statistical parameters attached to it (in the .HEAD file), then the nominal p-value is shown below the threshold slider.

For the fim (etc.) dataset types, the threshold brick is fixed. For the fbuc ("bucket") dataset type, any brick within the dataset can be used as the threshold. If the current "Function" dataset is the bucket type, then a pair of choosers labeled "Func" and "Thr" are activated. The latter lets you pick the threshold brick; the former lets you choose the functional brick.

The colors are computed from the functional brick. The colors of the data that pass the threshold are determined by the color slider to the right of the threshold slider, and by the "range" controls to the far right/bottom. By default, "autoRange" is on, which means that the maximum value in the functional dataset brick is mapped to the top value on the color slider (1.0). By clicking "autoRange" off, you can enter a value in the data field below, and that will be the value mapped to 1.0. For example, if you want to have values of 5.0 mapped to 1.0, you can type "5.0" in that field. Functional values over 5.0 are treated as equivalent to 5.0 in this mapping. If you want to turn those off entirely, you can do so by setting the top color of the color slider to "none" (click in a color panel to change its color value). Then choose the mapping range appropriately to get the colors you want with the remaining part of the color slider.

The number of color steps is chosen by the menu labeled "#" just below the color slider. The toggle switch labeled "Pos?" allows you to change the color slider data range from the default [-1..1] to be [0..1]. This is appropriate if your functional data is always non-negative (or if you just don't want to see the negative functional values). There is no way to display only negative function (unless you just set all the positive colors to "none").

It is also possible to change the upper range of the color slider away from the default value of 1.0. This is done using the Button-3 popup menu attached to the "Inten" label at the top of the slider. This feature, and other facets of the color slider, are more fully described in the file README.setup.

N.B.: It is important to realize that a functional value of zero will never cause a color overlay, even if it is in the range of one of the color slider panes.

[Answer edited 04 Mar 2000]

---

Q23. How do I get a list of Talairach coordinates?
If you want a list of the coordinates of the centers of mass of clusters of voxels in a dataset, the command line program 3dclust will do this for you. You can apply a threshold to the dataset to clip off the undesired voxels, and then set geometric criteria for the clustering operation.

If you want a list of the coordinates of all the voxels above some threshold, there really isn't a way to do that. It could be grafted into program 3dmaskave without much trouble, but so far there has been no such demand.

---

Q24. So how do the clustering parameters "rmm" and "vmul" work?
The clustering options (to programs 3dclust and 3dmerge, among others), put together voxels that are nonzero and spatially contiguous. The first step is usually to threshold the dataset in some way (this can be done on the command line of 3dclust, or can be done ahead of time with 3dmerge, 3dcalc, etc.).

The geometrical criterion for spatial contiguity is defined by the parameter "rmm". A nonzero voxel is defined as being in the same cluster as another nonzero voxel if their centers are within a distance of rmm millimeters. In a 3D lattice of cubical voxels with edges of length L, the range of common values of rmm are:

• L < rmm < 1.4142 L
  This will directly connect voxels that share a common face (nearest neighbors), but no others.
• 1.4142 L < rmm < 1.732 L
  This will also connect voxels that share an edge (2nd nearest neighbors), but have no nonzero voxel in common in the corner between them.
• 1.732 L < rmm < 2 L
  This will also connect voxels that share a corner (3rd nearest neighbors), but have no nonzero voxel in common in the corners between them.

Here, 1.4142 = sqrt(2) and 1.732 = sqrt(3). If the voxels are not cubical, you have to calculate the appropriate value of rmm for the connectivity that you desire.

The parameter "vmul" is used to delete (set to zero) voxels in clusters whose volume is less than vmul microliters (a microliter is a cubic millimeter). This is particularly useful when datasets have been resampled to a fine grid in Talairach coordinates. There may be small patches of above-threshold voxels that are smaller than one of the original data voxels. Thus, vmul should be at least as large as the volume of an original voxel, and you may want it to be 2 or 3 times larger than that.

Cluster Erosion and Dilation
The -1erode and -1dilate options to 3dmerge can be used to further massage the shapes of clusters. The basic idea is to try to cut off small "necks" (or peninsulas) that might connect larger regions, as in this picture:

   xxxxxxx         yyyyyyy
   xxxxxxx         yyyyyyy
   xxxxxxxaaaaaaaaayyyyyyy
   xxxxxxx         yyyyyyy
   xxxxxxx         yyyyyyy

This is easy to see in 2D, but hard to see when it is all twisted through 3D space--what looks like 2 separate clusters of activation may actually be detected by 3dclust (or 3dmerge) as 1, because of a small neck (like the a voxels) connecting the two larger regions.

By eroding the outer edges, the a voxels would be removed, along with the outer edges of the the x and y regions. Dilation from the surviving x and y regions will restore the x and y regions back to about what they were before, but the a neck will not come back (much).

For a single voxel neck, as illustrated above, setting the erode pv parameter to 50 should delete the a voxels, since you are requiring that 50% of the neighbors be in the cluster for non-erosion. Since there are 6 neighbors (in 3D, and assuming you have set rmm to cluster only nearest neigbors), and the a's only have 2 cluster neighbors each, they will be gone. So will the corner x and y voxels. Dilation will restore the corners, and also the first a voxels that stick out of the big regions, but the rest of the neck will be history.

Other Editing Options
The program 3dmerge has a number of other "editing options" that can be used to manipulate the data prior to clustering. Most useful among these, perhaps, is the -1thresh option, which will threshold the data before clustering. When using the newer bucket type of datasets (e.g., as generated by FIM+), you might need to select the correct sub-bricks for the data to be clustered and the thresholding. In 3dmerge, this is done with options -1dindex and -1tindex, respectively. These two options were just added to program 3dclust as well [16 Sep 1999]. If you are using an earlier version of the AFNI package, the only way to use a bucket dataset with 3dclust is to first use 3dmerge with the appropriate -1dindex and -1tindex options (and maybe -1thresh) to create a temporary dataset with the desired properties. (Or you could upgrade to the current AFNI.)

[Answer last changed 23 Sep 1999]

---

Q25. I wrote a plugin that worked, so why does it fail when I download a new version of AFNI?
The internal data structures that define a dataset may be altered when a new version of AFNI is released. If your plugin is not recompiled using the new header files, then it will be accessing the wrong locations in the C structs and it is unlikely that good things will results. If you download a new copy of the AFNI package, you should recompile all your own (private) plugins to be safe, after you recompile all the AFNI libraries. ("Private" means a plugin that isn't distributed with AFNI from MCW.)

At startup, AFNI now checks the compilation date of plugins and prints out a warning message if a plugin was compiled before the AFNI main program. This is intended to remind you of such potential conflicts. If you are only using plugins from MCW, this message should not occur, since the normal Makefile order builds the main program first and the plugins last.

---

Q26. How do I make a GIF animation?
The program whirlgif can create an animated GIF (for inclusion on a Web page, like this one) from a sequence of single frame GIFs. These can be created from pnm images saved out of AFNI using the program ppmtogif (part of netpbm). Whirlgif is included in the AFNI source code package, but must be compiled manually with "make whirlgif". See the output of "whirgif -help" for what documentation there is. (Whirlgif was written by Kevin Kadow; all I did was add the "-help" option.) The csh script gmovie that is included in afni_src.tgz can be used to convert a buch of PNM format images to a single animated GIF. You may need to tweak its operation for your particular needs, though.

Another program that does something similar is gifsicle. You can search for this (and many other things) at Google.

[29 Jun 2001] Now that AFNI can write GIF images directly from an image viewer (if you have netpbm installed -- AFNI just pipes the .ppm format through program ppmtogif), this makes it pretty easy to make animated GIFs. After saving the requisite .gif files, then issue one of the following commands

  whirlgif -loop -time 20 fred*.gif > anim.gif  # if you have whirlgif compiled
  gifsicle -d 20 -l -O fred*.gif > anim.gif     # if you have gifsicle compiled

[05 Aug 2001] AFNI now has the capability to run gifsicle (preferred) or whirlgif directly to produce Animated GIFs. AFNI can also use the program mpeg_encode to write a sequence of images into an MPEG-1 animation. These programs are supplied with the AFNI source code, but are not compiled by default. You can make them by issuing the command

   make gifsicle mpeg_encode

This will leave the program files gifsicle and mpeg_encode in the AFNI source code directory. You then must move these files to be in your path (perhaps in the same place you keep the rest of the AFNI executable files).

If these programs are installed, the image-viewer Disp control panel will have two new items: "Save Anim GIF" and "Save Anim MPG". Choosing one of these means that the next image sequence you write out using the image-viewer Save button will be written to a single animation file, rather than a set of single-image files. Note that if Save One is also selected, the choice of an animation format will override that selection, and the animation will be written. (Recall that Save One is the only way to write out a montage image layout.)

---

Q27. What are "-time:zt" and "-time:tz" in to3d?
When you input data to to3d, you give a list of filenames on the command line. to3d reads images from these files, 1 slice at a time. The order in which these slices are presented to the program determines if you want "-time:zt" or "-time:tz". Let's take an example where you have 8 slices and 99 repetitions. If you named your slice files im.[slice num].[time num] (im.1.01 .. im.8.01 all being gathered at the 1st repetition, then im.1.02 .. im.8.02 at the next repetition, etc.), then when you did an ls im.*.* on these files, they would appear in the order

  im.1.01 im.1.02 im.1.03 ... im.1.99 im.2.01 im.2.02 ...

This order is "-time:tz", since if you type "im.*.*" on the command line, they will appear in this order to the program. It is important to realize that this order is determined by Unix, not by the program. Wildcard characters (such as "*" and "?") are expanded into lists of filenames before the program is run, and the program only sees the resulting filename list, not the wildcards. (An exception is if you put the entire wildcarded filename inside forward single quotes, as in 'im.*.*'. Then Unix does not expand the wildcards on the command line. Instead, to3d will do the expansion internally, but the filename order will be the same as if Unix did it externally. This ability is provided to let to3d get around limitations on some Unix systems that restrict the length of an expanded command line.)

In this example, you would run to3d with a command like

  to3d -time:tz 99 8 3s alt+z [other options] im.*.*

where I've assumed your repetition time (TR) is 3 seconds. The "alt+z" tells AFNI that the images are spread out in acquisition evenly across the TR=3s, in alternating order (1 3 5 7 2 4 6 8), which is usual (but not universal) in MRI.

If instead, you named your files im.[time num].[slice num], then you would have to use

  to3d -time:zt 8 99 3s alt+z [other options] im.*.*

This is because the order in which the files would be listed when you type "im.*.*" would be z varying first, then t, since the slice index now appears after the time index in the filename.

If your files are 3D blocks, one at each time, then you will usually be inputting data in the "-time:zt" order, since each file will contain a bunch of z values at a fixed time. But some sites (e.g., MGH) gather all the data from one slice, all times, into one such 3D block. In this case, they would have to use "-time:tz".

For more explanations, see the to3d chapter of the auxiliary programs manual (afni_aux.ps), and the output of to3d -help. In particular, you will need to read these sections if your slices are gathered in some other time order than the one implied by "alt+z".

Filename Ordering
In the above example, I used filenames like im.A.B, where A was a 1 digit number from 1-8 specifying the slice, and B was a 2 digit number from 1-99 specifying the time order. If you had more than 9 slices, you would want A to be a 2 digit number; if you had more than 99 repetitions, you would want B to be a 3 (or 4) digit number.

Let's take a simple example: suppose you have just one slice and 99 repetitions, but the time points are labeled with a single digit when possible:

  im.1 im.2  im.3  ... im.9  im.10 im.11 im.12 ... im.97 im.98 im.99

When you use the wildcard im.* to input these files, you will find that the order in which they are read is

  im.1 im.10 im.11 ... im.19 im.2  im.20 im.21 ... im.29  im.3 im.31 ...

which is not useful at all. There are two solutions. The first is to use the "?" wildcard character, which matches just one character. In this case, you would use im.? im.?? on the command line, which would read all the 1 digit files first, followed by all the 2 digit files. The second solution is to rename all the files to use the same number of digits. The following C shell script will rename im.1 to be im.001, etc.:

  foreach fred ( `count -dig 3 1 99` )
    @ k = $fred
    mv im.$k im.$fred
  end

You can execute this by typing it in at the command line, or by putting it into a file (renum, say), and running it by typing source renum. If you have it in a file, then you can edit and re-use it later.

Ordering Files with Weird Names
Let's say you have files with names like this (from a real DICOM example):

  MR.1.2.840.113619.2.1.6637.3053478798.3.27.920368684
  MR.1.2.840.113619.2.1.6637.3053544334.3.26.920368684
  MR.1.2.840.113619.2.1.6637.3053609870.3.25.920368684
                                          **

The ** asterisks mark the location of the acquisition sequence number (in the example above, 27, 26, then 25 -- the 11th 'field' separated by periods). However, Unix will list them in order based mostly on the characters that precede this location. To get these files into order, the simplest This can be done with a C shell script like this:

  ls MR.1.2.* > q1
  sort -n -k11 -t. q1 > q2
  set ii = 1
  foreach fred ( `cat q2` )
    set jj = `count -digits 4 $ii $ii`
    mv $fred im.${jj}
    @ ii = $ii + 1
  end
  /bin/rm -f q1 q2

The first line of this script creates file q1 as a listing of the files to be renamed. The second line of the script sorts the file q1 numerically (not alphabetically) using the 11-th "field" (that's what the -k11 on the sort command line means), where the fields are separated by the "." character (which is what the -t. means). sort is a Unix system command - see man sort for its details. Then the foreach loop reads the sorted filenames from the q2 file and renames them to im.0001, etc. Finally, the temporary files q1 and q2 are removed.

It would also be possible to use the sorted list directly in a command like to3d `cat q2`, where the backquotes would place the sorted file list onto the command line. However, these filenames are so long that this procedure will likely overflow your computer's limits on command line length (at least, it does on our SGIs).

[Later] The "-@" option to to3d now will let you read file q2 onto the command line, without the limits of the shell or operating system. In this example, you would use the command to3d -@ < q2, and so would only need the first two commands above to create the q2 file. Or, if you have a great deal of confidence, you can do it all in one command with
ls MR.1.2.* | sort -n -k11 -t. | to3d [options] -@
thus eliding both the need to create a temporary file to hold the filenames, and the need to rename the input files. For more details, see Q32.

3D+time Functional Datasets?
You will find that the graphical interface in to3d does not allow you to create a time-dependent functional dataset. This is because I (and therefore AFNI) view the raw EPI time series as "anatomical" data, and "functional" datasets are those that directly reveal something about functional activity. Thus, functional datasets are computed from anatomical 3D+time datasets.

The principal difference between functional and anatomical datasets in AFNI is that anatomical datasets are used as the grayscale underlay images and functional datasets are used to create the color overlays. This was a design decision made back in the old days (summer 1994). If I were doing it over again, I would probably not make this distinction, but it's there.

Anyhow, you can create a 3D+time functional dataset of the "fim" type using to3d. This can be done by using the -fim switch on the to3d command line. If you forget this, you can use 3drefit to change the dataset type afterwards, as in

  3drefit -fim zork+orig

Such a dataset can be used as a functional overlay, and you can scroll through it with the Time Index control (but note that the time index of the anatomical and functional dataset will be linked). However, for many purposes, it would be better to create a multi-brick functional dataset as a "bucket" dataset ("fbuc" type, switch -fbuc in 3drefit).

If you want the same data to be both anatomical and functional, you must create 2 datasets. You can avoid the disk overhead of this by using the 3ddup program. After creating an anatomical dataset (say bob+orig), then you can create a "warp-on-demand" fim copy of this with just a .HEAD file with the command

  3ddup -fim -prefix bobfunc bob+orig

When AFNI needs to display images from bobfunc+orig, it will take the data out of bob+orig. Such warp-on-demand datasets can only be used for 2D image display purposes. If you want to process them in other ways, they must be written to disk - there must be a .BRIK file created using one of the AFNI Write buttons.

Note that is is not possible or legal to create a functional 3D+time dataset of any other type than "fim". This is because there is no support in any AFNI code for time-dependent data that has more than one value per voxel per time step; for example, you can't have a 3D+time "fico" dataset. I can certainly visualize situations in which such multiple-valued 3D+time data would be useful (e.g., combined gradient-echo and spin-echo EPI). Someday, maybe this capability will be put into AFNI. Then again, maybe not.

[Answer last changed 24 May 2001]

---

Q28. Can I resample to a non-cubical grid using AFNI?
No. I understand that the AIR program from Roger Woods (at UCLA) can do this. Check out http://bishopw.loni.ucla.edu/AIR3/index.html.

If your goal is to resample your functional data in Talairach space back to a grid that is similar to the original data grid, this may not be such a good idea. In the transformation to Talairach coordinates, the original data grid is rotated and rescaled (and rescaled differently in different parts of the brain, for that matter). The original slices are not likely to be parallel to the new coordinate system, or have the same thickness. Resampling to a coarse non-cubical grid can make these changes very visible, and produce funny looking artifacts.

---

Q29. How would you configure a Linux system for AFNI?
A good Intel/Linux system (but not really cheap) would be

• 800 MHz+ MHz Pentium III/IV or Athlon (but not Xeon - doesn't provide much speedup).
• As much RAM as you can cram in (256-1024 MB).
• Dual 18 GB SCSI disk drives (or dual 36 gigs, or more!).
• Some data backup system: DDS-3 tape, CD recorder, ....
• 20-21'' monitor, configured to run at 1600x1200 (or an LCD panel!).
  • Even better are dual display systems, which I'm using and really enjoying.

In general, SCSI disks are preferred to IDE because of faster I/O, and much better performance when multiple streams of I/O are being carried out. If you are concerned about price, IDE works OK as long as only one major disk operation is happening at a time (e.g., you don't run two big programs at once). I personally do most of my development work on a IDE-based system. But I'm not really involved in big-time data analysis, so what do I know?

If you are not comfortable installing Linux yourself, there is a large number of vendors who will build a computer for you, install Linux (and Windows), and ship you the system. A list of companies that sell computers with Linux pre-installed can be found here -- one vendors I have used successfully in the past is ASL Workstations [this is not an endorsement, just a statement of fact].

AFNI itself is developed to be compatible with all the Unix systems to which I have regular access. This means (in order of importance) Intel-x86/Linux, SGI-MIPS/IRIX, Sun/Solaris, Mac OS X, and HP-PA/HP-UX. Compatibility with other systems is by luck, mostly. I have heard of people using AFNI on IBM/AIX, DEC, and OpenBSD. Not having one of these systems handy, I can't help if you run into trouble on one of them.

---

Q30. How can I do Region-of-Interest (ROI) analyses?
A few tools for selecting voxel subsets and extracting their data for external analysis are included with AFNI 2.20. These tools are quite new and crude, and (God willing) will be improved as time goes on. Nonetheless, it is possible to do some useful work with them now.

The ROI stuff is mostly implemented as a set of plugins. These all have extensive help, so I won't give all the details here. You may need to write some C programs to calculate useful results after extracting the data you want.

Selecting a ROI: plugin "Draw Dataset"
This plugin lets you draw values into a dataset brick. The idea is to start with a dataset that is all zeros and then draw nonzero values over the desired regions. An all zero dataset of a size equivalent to an existing dataset can be created using the "Dataset Copy" plugin. Another way to create a starting point for a mask dataset would be to use the "Edit Dataset" plugin or the 3dmerge program (e.g., to pick out all voxels with a correlation coefficient above a threshold).

Normally, you would create the mask dataset as type "fim". This would allow it to be displayed as a functional overlay on the anatomical background.

Mask datasets tend to be mostly zeros. You can use the ability of AFNI to read/write compressed datasets to save disk space. See the file README.compression and the plugin "BRIK compressor" for details.

To be useful, a mask dataset must be created at exactly the resolution of the datasets it will be used with. This means that if you create a mask at the anatomical resolution, the functional datasets to which you apply it must be at that resolution also. This isn't a problem in the +acpc or +tlrc coordinate systems, but is an annoyance in the +orig data. Sorry about that. (But see the program 3dfractionize, described below.)

The drawing plugin is rather tedious to use. An adaptation of it, written by Rick Reynolds (formerly of MCW), is also now distributed with AFNI. This appears as Gyrus Finder on the Plugins menu. It allows you to set some bounding planes, and then select voxels inside these planes based on the gray level of the anatomical dataset. You can then clean up the results using drawing tools. The only documentation for this plugin is in its online help.

Averaging Data Defined by a ROI Mask: program 3dmaskave
This program lets you compute the average over a ROI of all voxel values from an input dataset. (It is also possible to extract all the voxel values and save them for other analysis.) The ROI is defined by a mask dataset. The average value is computed for each sub-brick in the input, so you can use this to create an average time series. The output is written to stdout - it can be redirected (using '>') into a file. For more information, try "3dmaskave -help". An alternative to this command-line program is the similar plugin "ROI Average", which you can use interactively from within AFNI.

Averaging Several Distinct ROIs at Once: program 3dROIstats
This program, by Tom Ross of MCW, can do something similar to 3dmaskave, but does a separate average for each separate value found in the mask file. In this way, you can have multiple masks defined in one mask file, the first defined by putting 1 into some voxels, the second by putting 2 into some voxels, etc. (3dmerge can do this using the -1clust_order option, for example. Or you could use the Draw Dataset plugin to draw multiple anatomical ROIs using distinct voxel values.) Then 3dROIstats can extract the average over each ROI for you, all in one operation (vs. running 3dmaskave many times).

Extracting Data from ROIs into an ASCII File: program 3dmaskdump
This program will write one line for each voxel that meets the mask criteria. Multiple values (from multiple sub-bricks of multiple datasets) can be written to each line. This format is suitable for import into a spreadsheet program (say) for further analysis and graphing.

[03 Oct 2000] The new program 3dUndump can be used as an inverse to 3dmaskdump, in that it will let you create a dataset from a list of voxel coordinates and values.

Resampling a ROI Mask to a Lower Resolution: program 3dfractionize
This new program (07 Feb 1999) lets you take a mask dataset produced at higher resolution (e.g., by drawing over an anatomical dataset) and resample it down to a lower resolution (e.g., a typical EPI dataset). The new mask can then be used in the normal ways described above. Fractionize refers to the fact that the program computes the fraction of each output voxel that is occupied by nonzero input voxels, handling the cases of possible overlap correctly (we hope). Normally, you would clip off voxels that had too small a fraction touched by the input mask. This clipping can be done with 3dfractionize itself, or later using one of 3dmerge, 3dcalc, or 3dmaskave. At present, the only documentation for 3dfractionize is the output of the command 3dfractionize -help.

The following documentation is by Michael S. Beauchamp of the NIMH:
One of the most useful ways to visualize FMRI data is an average MR time series from a group of voxels. AFNI makes this easy, with the "ROI Average" plug-in or the "maskave" stand-alone program. The user inputs a mask BRIK specifying which voxels to average, and a 3D+time BRIK containing the time series data. AFNI then outputs a text file with the average value at each time point (and standard deviation, if desired) which can be graphed in Excel or any other plotting program.

Some difficulties arise when the mask BRIK and the 3D+time BRIK have different coordinate spaces or voxel dimensions. In these cases, 3dfractionize may be used to translate between the different datasets.

Also see this useful page from Brown University.

[Answer last changed 26 May 2000]

---

Q31. What are the angles reported from 3dvolreg?
The names are chosen from the angles used in describing the motions of aircraft or ships. (Imagine lying down with your arms out, pretending that you are an airplane. It is not necessary to make zooming noises during this mental exercise.)

• Roll is the angle about the Inferior-to-Superior (I-S) axis. It corresponds to the motion one makes when shaking the head "NO".
• Pitch is the angle about the Right-to-Left (R-L) axis. It corresponds to the motion one makes when nodding the head "YES".
  (This is the motion my Chairman is supposed to make when I ask for a large raise.)
• Yaw is the angle about the Anterior-to-Posterior (A-P) axis. It involves rocking the ear towards the shoulder.

You could use the program 3drotate to move some dataset in each direction (one at a time) in order to see these effects.

The new [12 Feb 1999] program 1dplot makes it possible to graph the "-dfile" output from 3dvolreg to the display, and thence to a PostScript file. It can also be used to graph arbitrary *.1D format files, but for better control over such graphs, you should use program xmgr, available here, or use some other dedicated graphing program.

By the way, the displacement estimates output by 3dvolreg are in millimeters, and the angles are in degrees. This fact is mentioned in the output of 3dvolreg -help, but some people seem not to notice. One reason for these choices is that the typical FMRI experiment (at least with experienced normal volunteers) results in motions of about 1 mm and/or 1 degree, in my experience.

If you would like short description of how 3dvolreg works, see the end of file README.registration. For a longer description, you can download a PostScript preprint of a paper recently published in Magnetic Resonance in Medicine [Dec 1999].

[Answer last changed 10 Dec 1999]

---

Q32. What are "Arg list too long" messages?
Errors like this occur when you create a command line that is larger than the operating system allows. This is a particular problem on SGI IRIX systems. If the problem is arising with to3d, one way around it is to use internal wildcard expansion on the input filenames - see Q12.

If the problem is that you want to input a lot of files to a statistics program, such as 3dRegAna, another approach is needed. If you make the last option on the command line be "-@", then the program will copy the contents of standard input (stdin) to the tail of the command line. (This feature is part of the AFNI package, not a part of Unix.) You can use this in one of two ways:

• 3dRegana -@ < filename

  where filename contains the information to copy onto the command line. (This file may have linebreaks -- it doesn't have to be one big line. No line should have over 4000 characters, though.)

• 3dRegana -@ << ENDSTRING
  options
  more options
  ....
  ENDSTRING

  This method uses a feature of the shells csh and sh, where the standard input of the program is read from the input file (rather than the user's terminal) up until a line that matches the characters just to the right of the "<<" -- in this case, I've used "ENDSTRING" as this marker. An advantage of this method is that the inputs for the program are in the same shell script that you are using to run the program, rather than being in a separate file. If you choose to use this technique, a glance at the man pages for your shell of choice would be in order.

This "-@" method was implemented 22 Feb 1999, and so is still experimental. At this moment, it has only been retrofitted into program 3dRegAna.

[20 Apr 2001]: This method is now implemented into the following programs:

3dANOVA2 3dANOVA3 3dANOVA 3dbucket 3dcalc 3dDeconvolve 3dDetrend 3dfim 3dfim+ 3dFriedman 3dKruskalWallis 3dMannWhitney 3dmaskdump 3dMean 3dmerge 3dNLfim 3dOverlap 3dpc 3drefit 3dRegAna 3dROIstats 3drotate 3dStatClust 3dTcat 3dttest 3dUndump 3dvolreg 3dWavelets 3dWilcoxon to3d

If there is a program missing from this list for which you need this functionality, please let me know. It only requires pasting 4 lines of C code into the program to add this capability.

Note Well: Each group of characters read in by "-@" separated by "whitespace" (blanks, tabs, newlines) will be appended as a separate argument to the program.

• In particular, you cannot embed a blank in an argument using quotes, unlike if the argument were actually on the command line.
• The shell does not do filename expansion (globbing) on "-@" data, so you do not escape or quote wildcards such as the *?[] characters.
• If you use the "<<" input method described above, the shell does do $ variable expansion on the input lines, so any dollar signs in the input stream need to be escaped with the backslash \ character: \$ (that is, unless you want shell variables to be expanded there).
• Not all the above programs have been tested with "-@"; please let me know if there are any problems.

---

Q33. How can I avoid running out of memory in to3d?
to3d assembles the new dataset into RAM before writing it to disk in the .BRIK file. As it is reading 2D slices from the input files, it will need to have in memory one input file at a time and also the entire new dataset. If the input file comprises all the new dataset, this means that twice as much RAM is needed during input as is needed to store the new dataset brick(s). (The code was written this way because our image reconstruction software gives us our images as individual slice files. In this case, the overhead is just the amount of memory needed for one slice, which is trivial.)

To avoid this problem, the "-in:1" switch was added to to3d. If you use this, then only one 2D slice will be read out of each input file at a time. When inputting a big 3D or 4D file, this results in somewhat more disk I/O, but saves a lot of memory.

On HP-UX systems, another problem is that HP seems to ship the Unix kernel configured so that each running program can only access 64 MB of RAM, no matter how much the system actually has. To fix this, the super-user (root) has to use the SAM program (part of HP-UX) to adjust the kernel parameters, and then rebuild the operating system. Ugly, but true.

---

Q34. How can I avoid having AFNI convert the symbolic links in my session directory names?
You can do this using the AFNI_NOREALPATH environment variable. For details, see file README.environment.

---

Q35. What does the "Intensity" computed by FIM mean?
The "FIM intensity" is defined on page 22 of the manual afni200.ps. It is the parameter alpha in the least squares fit of each voxel time series x(t) to the model

  x(t) = alpha * r(t) + a + b*t + noise

where r(t) is the reference waveform you supply. Thus, if you double r(t), alpha will be halved; alpha is the amount of r(t) present in x(t), as computed by linear regression.

The "Compute FIM+" menu item in an AFNI graph window has the ability to compute percent change in addition to the fit coefficient alpha. In this module, "percent change" is defined from the baseline in the absence of function, not from the average time series value including the function. r(t) is linearly scaled and shifted to be between 0 and 1 (no matter what the input range actually is), and then the fit above is computed. The baseline is a + b*tmid, where tmid is the middle time point, and the percent change is 100*alpha/baseline. (If other orts are present, baseline is defined as the average value of the fit of all the orts, including the implicit orts 1 and t, whose coefficients are a and b in the equation above.)

Note that this will often produce some huge percent changes of low significance outside the brain (where the baseline is small), so that the range of the "% Change" sub-brick will be large (cf. Q49). For proper color overlay display of 5% (say) signals, you will have to turn off the autoRange toggle on the "Define Function" control panel, and enter the desired range in the parameter box directly below.

Finally, note that the -percent option of 3dfim does something slightly different: it computes the absolute value of the percent change from the time series mean (which will include the mean value of the function). Why is this different from the "FIM+" module within AFNI itself? There is no good reason. (See also the answer to Q41.)

---

Q36. How can I count the number of voxels above threshold in a functional dataset?
There are 2 slightly clumsy ways to do this counting, one from the command line and one from a plugin. They are basically the same.

From a plugin: use the ROI Average plugin. Choose the Source and Mask datasets to be the same. Choose the sub-bricks to be the same, and to be the one you want to threshold on (e.g., for fico datasets, the correlation coeffient is in sub-brick #1 -- in general, you can use the Define Datamode->Misc->Func Info item to get information about a dataset's sub-bricks). Use the Range control in the plugin to set the range of values from the sub-brick you want to include (e.g., for fico datasets, you might set the range to be 0.5 to 1.0 to include all voxels with correlation coefficient between these values). Then press Run+Keep and you'll get a popup window with the summary information you want.

The same thing can be done using the 3dmaskave command line program - which isn't surprising, since the plugin and the program are almost identical, except for their interfaces. See the output of 3dmaskave -help for the details.

What you are doing is creating a mask on-the-fly, by applying a threshold to a dataset sub-brick, rather than by drawing one manually with the Draw Dataset plugin. If the dataset were already thresholded externally (e.g., in 3dmerge), then you wouldn't have to use the Range controls, and just use the whole dataset itself as a mask for itself. Voxels that are zero in the mask sub-brick, either because they were zero ahead of time or were thresholded away using the Range controls, do not count in the calculation of the output.

A related problem is to count the number of voxels that meet two criteria; for example, the number of voxels in a FIM+ dataset with correlation coefficient greater than 0.4 and that have a Best Index value of 4. This can be done using 3dmaskave (but not the plugin) with a command like

  3dmaskave -mask name+orig -mindex 3 -mrange 0.4 1.0 -dindex 1 -drange 4 4 name+orig

Sub-brick #3 (Correlation) is thresholded, keeping only values between 0.4 and 1.0 (inclusive). Then sub-brick #1 (Best Index) voxels whose value is between 4 and 4 (inclusive) are counted up. (Program 3dinfo can be used to find out what sub-bricks are stored in a dataset.) The output of 3dmaskave will be something like

  +++ 987 voxels survive the mask
  4 [130 voxels]

The first line says that 987 voxels were above the correlation threshold of 0.4 that was set with the -m* options to 3dmaskave. The second line says says that the average value of the selected voxels was 4 (not surprising here, since only allowed values of exactly 4 were counted), and that 130 voxels went into this average.

---

Q37. How can I more easily control the initial colors in the functional overlays?
There are two ways to control this, both of which involve setup files.

The first is to set some values in your .Xdefault (or .Xresources) file in your home directory, which is read by the X11 graphics server when you login. When AFNI starts, it will query the server for resource values that start with the string AFNI. The full list of values that the program looks for is given in the sample file AFNI.Xdefaults, which is distributed with the AFNI source code.

The second (and better) method is described in detail in README.setup.

---

Q38. How can I "upsample" an image to higher resolution?
Higher resolution is not achievable, but smaller pixel sizes are. (Resolution means the ability to distinguish features; merely going to a smaller pixel size will not help. But it can make an image look better, especially when zoomed.)

The new [16 Apr 1999] program imupsam will take as input a 2D image (floats, shorts, PGM, or PPM) and upsample it to a finer resolution, using 7th order polynomial interpolation in each direction.

---

Q39. What is the format of a .BRIK file?
A .BRIK file contains nothing but voxel values. If a dataset has 1 sub-brick, which is 100x100x100 voxels, and the values stored are shorts (2 bytes each), then the .BRIK file will have exactly 2,000,000 bytes. All the formatting information is stored in the .HEAD file. For example, this .BRIK file would also be compatible with a 1000x100x10 array. The dimensions are stored in the .HEAD file, along with the voxel sizes, location in the magnet, and other such auxiliary information.

---

Q40. What is the format of a .HEAD file?
I thought you'd never ask. However, the answer may not be entirely satisfactory.

The .HEAD file for an AFNI dataset is in ASCII, so you can view it with a normal text editor (e.g., vi - the editor for real men). The data within are organized into what I call "attributes", which are named arrays of floats, integers, or characters (strings). A sample float attribute is

  type = integer-attribute
  name = DATASET_DIMENSIONS
  count = 5
  256 256 124 0 0

This particular array defines the voxel array dimensions. An example of a character array attribute is

  type = string-attribute
  name = IDCODE_DATE
  count = 25
  'Mon Apr 15 13:08:36 1996~

Note that the data for a string attribute starts with a single ' character, and that the number of bytes is given by the count parameter. The ASCII NUL character is replaced by the tilde ~ so that the .HEAD file can be edited manually, if need be. On input, tildes will be replaced with NULs.

Unfortunately, I've never documented the list of attributes that are used by AFNI. The use that AFNI makes of each attribute can be inferred (perhaps) by perusal of the code in thd_dsetdblk.c; the many macros defined in 3ddata.h will be needed to decipher this routine. The dataset reading code (see file thd_opendset.c and routines called therein) requires a minimal set of attributes to be able to decipher a dataset; for example, the DATASET_DIMENSIONS attribute above is required. There are also some attributes that are not mandatory for a dataset to be successfully constructed from a .HEAD file; for example, the IDCODE_DATE attribute above is not required. Attributes that AFNI doesn't know how to deal with are ignored. This makes it possible for a program to tuck extra information into the .HEAD file and not cause trouble.

The order in which the attributes occur is not important. AFNI reads all the attributes into memory at once, then searches for them by name as needed in the dataset construction code. On the other hand, an improperly constructed attribute (e.g., one with the count value given incorrectly) may make the .HEAD file unreadable at all. This is why manually editing a .HEAD file should be done very carefully.

[28 Mar 2001]: I've finally documented the attributes in a .HEAD file, and you can read that information here.

Q41. What are the FIM+ sub-bricks?
The Compute FIM+ menu item (on the FIM menu in a graph window) calculates a "functional bucket" dataset that contains up to seven sub-bricks. In each voxel, these values are computed from the data time series x(t) as follows (cf. Q35):

• Fit Coef
  This is the least squares estimate to the fit coefficient a in the time series model
  x(t) = a r(t) + b + c (t-tmid) + orts + noise ,
  where r(t) is the reference (or ideal) waveform, and tmid is the time in the middle of the scan. Note that magnitude of a will depend on the magnitude of r(t), since doubling r(t) will perforce require halving a.
• Best Index
  When more than one time series r(t) is in the *.1D file chosen as the ideal, then this is the index of which one gave the best fit (in the least squares sense) to the time series model. The index starts at 1. If the different r(t)'s are just time shifted versions of each other, then the Best Index can be used as a crude estimator for hemodynamic delay.
• % Change
  If r(t) is normalized to vary between 0 and 1, then this is equal to 100 a/baseline. Since the user may input an r(t) that is not normalized to lie between 0 and 1, the program allows for this in the calculation. The baseline used is equal to a min[r]+b, plus the sum of the averages of the orts (including the constant and linear trend).

  Please note that the % Change computed in the interactive AFNI is not the same as that computed in the program 3dfim. This is because the two programs were written by two different people. The difference is that 3dfim uses the time series mean as the baseline, rather than the calculation described above. The difference is usually small. When will this difference be reconciled? [begin music] The answer, my friend, is blowing in the wind. [end music]

• Baseline
  This is just the baseline estimate described above. It is not computed by default, but can be enabled from the Compute FIM+ menu.
• Correlation
  This is the correlation coefficient of x(t) with r(t), after detrending the baseline and the orts:
  xd(t) = x(t) - b - c (t-tmid) - orts .
  Then the correlation coefficient estimate is
  rho = sum[ xd(t) r(t) ] / { sum[ xd(t)**2 ] sum[ r(t)**2 ] }**0.5 .
  In terms of the Fit Coef a, this can be written as
  rho = a sum[r(t)**2]**0.5 / { a**2 sum[r(t)**2] + sum[noise**2] }**0.5 .
  This shows that as a gets large and positive, the correlation tends to 1.

  If r(t) is a square wave ("boxcar" function), then thresholding on rho is mathematically equivalent to thresholding a t-statistic between the "on" and "off" intervals. This elementary fact has appeared several times in the FMRI literature, but still does not seem to be widely known.

  One disadvantage of using rho as a measure of activation magnitude is that its definition not only contains the BOLD response a r(t), but also contains the noise level. That is, two otherwise identical voxels with different amounts of noise will have the same a (and the same % Change), but will have different values of the correlation coefficient. For this reason, I usually recommend using either the Fit Coef or the % Change as a measure of the BOLD response.

• % From Ave
  This is the same as % Change, but the denominator is each voxel's average rather than baseline. For positive signals, this will result in a smaller value than the % Change, since the baseline will be larger. For negative signals, the opposite will occur.
  [Requested by Andrzej Jesmanowicz of MCW, 08 Sep 1999.]
• Average
  This is the average value of each voxel's time series, as computed by the linear regression underlying the FIM calculations.
• % From Top
  This is the percent signal change again, but the denominator is each voxel's peak value rather than the base or average value.
• Topline
  This is the estimate of each voxel's peak value, as fit by the linear regression.
• Sigma Resid
  This is the estimate of each voxel's residual standard deviation, after the linear regressors (ideals and orts) have been subtracted.

Note that the time points ignored in the calculations (either using the Ignore menu, or using the ignore setting in the ideal file) are not included in the calculations described above.

By default, the FIM+ computations calculate the following values:

    Fit Coef   Best Index   % Change   Correlation

You can select a different subset from the FIM+ submenu of a graph window's FIM menu. It is also possible to set a different default set of calculations by modifying the environment variable AFNI_FIM_MASK. Other environment variables can also be used to affect the FIM and FIM+ calculations - see file README.environment.

[Answer last changed 04 Jan 2000]

---

Q42. I duplicated a plugin and then edited it, but can't get both it and the original to work at once!
This problem can arise when two separate plugins have routines with the same name, which is likely to arise when you create one plugin by copying and changing another. The two ways around this problem are

• Change all the function names in the copy.
• Declare all functions (in both plugins) as static (except for PLUGIN_init).

This difficulty has only been observed on HP-UX systems. SGI IRIX and Linux systems correctly handle the name space separation between different dynamic objects.

---

Q43. I installed the AFNI package, but when I try to run a program, I get a 'not found' message!
Your problem is that the shell you are using is not finding the program you are trying to run. After you compile the AFNI binaries (or unpack them from one of the binary distributions), you need to install them in a place in the list of directories that the system searches for executable files. This list is called your "path". If you are using the shell csh or tcsh, you can add a directory to the path the system gives you with a command like

  set path = ( $path /new/directory/name )

If you are using the Bourne or Korn shells (sh, bash, or ksh), the equivalent action is

  PATH=${PATH}:/new/directory/name ; export PATH

Normally you would put such commands in the shell startup file in your home directory (.cshrc, .profile, or .bashrc, depending on your shell). This file contains a list of commands that will be executed when the shell starts. Note that editing this startup file will not cause the file to be re-executed, so the path will not change immediately. For this to happen, you will have to logout and login again, or otherwise start a new shell.

The "shell" is the program that you are typing into when you issue commands explicitly (rather than by pointing and clicking). It handles things like wildcard expansions, environment variable settings, etc. You should probably become familiar with the capabilities of your shell by reading the Unix man page for it (print it out and use it for bedtime reading).

---

Q44. When trying to compile AFNI, I get messages like "Xm/Xmall.h not found"!
Your problem is that the Makefile isn't finding the Motif library files on your system. One possible cause is that the compiler isn't searching for the files in the right place. The search path is controlled by the -I and -L switches to the compiler. You may need to modify these in your Makefile, assuming you can find the place where Motif is installed.

If you are using Linux, the more likely cause is that you don't have Motif installed. Motif is the software that is used to build the AFNI graphics interface (layered on top of X11 and Xt). Motif is not free software (unlike X11 and Xt), and so doesn't come automatically with Linux. You have to buy it, at about US$100-150 per machine. RedHat sells it, as do a number of other places. AFNI also works fairly well with the free LessTif libraries (but be sure to get the latest version).

[15 May 2000] Motif source and binaries are now available free from their owner, the Open Group. Go here for more information, or try here.

---

Q45. If I change a timeseries file, why doesn't Rescan *.1D re-read it?
As you may have discovered, Rescan *.1D only reads new filenames, and won't re-read data from filenames that it has seen before. This is a feature, not a bug. Really.

As I recall my thinking at the time, the reason is that when you select a *.1D file to be an ideal, AFNI makes an internal copy of it (this happens at other places, too) - a copy is made because you are allowed to edit the ideal inside AFNI. So if the *.1D file were re-read after it was altered, you'd expect the internal copies (e.g., the one being plotted as the ideal) to be updated as well. But then AFNI would have to keep track of what functions have a copy of a now modified time series, and then update them. This would be too much like work.

If you are repeatedly modifying a timeseries file (e.g., using waver), Rescanning, and deciding if it is acceptable, I would recommend renaming the new file each time (e.g., to elvis_1.1D, then elvis_2.1D, etc.).

---

Q46. Can you supply me with the images from the Talairach-Tournoux Atlas?
No! These images are copyrighted, and duplication/distribution of them would get me into big trouble with the publisher of the Atlas (Thieme). Sorry about that.

---

Q47. How can I use the volume renderer to deal with arbitrary datasets?
The design of the rendering plugin was motivated by several factors:

• Lack of time to deal with the complexity of non-identical grids and coordinates in the overlay and underlay bricks.
• The fact that this was the first time I ever used volume rendering.
• The belief that people were most likely to use this on Talairach datasets, which are usually identical in conformation.

As a result, the two input datasets are required to be stored on identical grids, with cubical voxels, and with axial slice orientation (as is output in the +tlrc and +acpc coordinate systems).

It is possible to force a dataset into this mold, but it is a little clumsy. There are 3 steps:

1. Use the 3ddup program to make a "warp-on-demand" (.HEAD file only) copy of a dataset; for example:

    3ddup -prefix aaa anat+orig
    3ddup -prefix fff r1:time@1+orig
   

   makes the datasets aaa+orig and fff+orig, which are copies of the anatomical and functional datasets.
2. Run AFNI, open up the Datamode control panel, and turn on "Warp Anat on Demand" and "Warp Func on Demand". Set the "Resam mode" for Anat and Func, and maybe set the Resam voxel size, too (default here is 1 mm). Then use the "Write Anat" and "Write Func" buttons to write out the aaa and fff datasets (if necessary, you'll have to use Switch so that these are the current datasets). This will give them .BRIK files. (Do NOT use "Write Many" to write them out in one operation!) Exit AFNI now.
3. Unless these datasets are axial (that is, 3dinfo shows that they are stored in "-orient RAI"), you next must create axial slice versions of these dataset. This is done with the 3daxialize program, as in

   
     3daxialize -prefix aaa_ax aaa+orig
     3daxialize -prefix fff_ax fff+orig
   

   You can now delete aaa+orig.* and fff+orig.*, since the axialized datasets contain the same data, just reordered into axial slices.

You can now restart AFNI, and the renderer should be able to deal with the new datasets aaa_ax+orig and fff_ax+orig.

Some people want to know how to resample one dataset so that it is forced to be on the same grid and volume as another. This can be done using the Write function of AFNI, as well. The trick is to know that the output grid and volume for the Function dataset are defined by the current Anatomy dataset. For example, suppose you have an angiography dataset you want to visualize on the same 3D grid/volume as another anatomical dataset. The first step is to use 3ddup as above on the angio dataset, but to also make it be a functional type, as in the command below:

  3ddup -fim -prefix angio_dup angio+orig

Then you can start AFNI, set the Anatomy to be the master dataset whose 3D grid/volume you want to use, and set the Function to be angio_dup; you may also want to alter the Func resample mode. Then do Write Func. Quit AFNI, and do the 3daxialize thing on angio_dup+orig, and then change the result back to be an anatomical dataset:

  3daxialize -prefix angio_ax angio_dup+orig
  3drefit -spgr angio_ax+orig
  rm -f angio_dup+orig.*       [this is optional, of course]

You will now be able to view the new dataset angio_ax as an anatomical underlay, either in the normal image viewing windows or in the rendering plugin, and it will cover the same volume as the anatomy master dataset you chose when you wrote to disk.

[Answer last changed 21 Oct 1999]

---

Q48. How can I turn off the "Splash" window that AFNI starts with?
If you really want to do this (why? don't you like my face?), set the Unix environment variable AFNI_NOSPLASH. For more details, see file README.environment.

---

Q49. How can I suppress the spuriously large % Change values from FIM+?
Voxels in the noise region have a very small baseline, and so can have a very large % Change value reported. This huge value can cause the true smaller % Change values to be lost in the quantization to 16 bits used in the final step of FIM+. To avoid this problem, set the Unix environment variable AFNI_FIM_PERCENT_LIMIT to something reasonable - 100, say. [08 Sep 1999: this setting also sets a limit on the value of the % From Ave sub-brick - see Q41.]

While I'm on the subject, the environment variable AFNI_FIM_BKTHR can be used to set the threshold for the suppression of the noise background in the FIM and FIM+ computations. For more details on these (and other) environment variables in AFNI, see file README.environment.

---

Q50. Is there a faster way to average datasets than using 3dcalc?
Yes; program 3dmerge with the -gmean option should execute faster and can also deal with more than 26 inputs. Also, program 3dMean does essentially the same thing, and is specialized for this purpose (so has many fewer options to wade through than 3dmerge).

3dcalc uses a general purpose expression parser that I wrote for other purposes (part of an imaging radar simulation) in Fortran, back about 1984. It isn't very efficient compared to compiled C code, but it is handy for "one off" calculations.

---

Q51. After 3dmerge, I don't have any threshold data?
Generally, this is correct (the exceptions are when the -keepthr and the -doall options are used). You can use the program 3dbucket to assemble sub-bricks from multiple datasets into a new dataset. AFNI can then view these "functional bucket" datasets using any one sub-brick as the color-determining intensity and any one sub-brick as the threshold value. See the documentation files /pub/dist/doc/3dbucket.ps and /pub/dist/doc/buckets.ps for more details on how to create buckets.

---

Q52. How can I do a t-test on time series data?
There are two possible ways to do intra-dataset comparisons to get a t-test result. The first is to use program 3dttest. At present, this requires breaking the input dataset into pieces, 1 sub-brick per dataset, since 3dttest can only read 1 sub-brick datasets. You could do this break up with the command line program 3dbucket, used once for each sub-brick to be extracted. This would be ugly, but possible.

The second way is to use the FIM analysis with the ideal set to be equal to 1 for the "on" periods and equal to 0 for the "off" periods. A correlation with such a 0-1 valued ideal function is mathematically equivalent to a t-test between the "on" and "off" time points. The correlation coefficient that is returned can be converted to a t-statistic via the formula

  t = sqrt(n) * r/sqrt(1-r*r)
  where r = correlation coefficient
  n = number of degrees of freedom = N-2
  N = number of points in the time series used in the analysis.

There is no particular reason to do this conversion, since the results of a correlation analysis are statistically identical, and since AFNI will show the nominal p-value for either type of statistic.

[Later]: If you are doing a correlation with multiple ideals, then the program assumes you are approximately optimizing over a 1 dimensional set of functions. This changes the distribution - it is no longer equivalent to a t-test after the above transformation. Instead, if you want to convert the correlation coefficient to some more familiar statistic, you should use the equation

  Nt-Nort-Nfit     r**2
  ------------ * -------- = F(Nfit,Nt-Nort-Nfit)
  Nfit         1-r**2
  where
  Nt   = number of points in time series used in correlation
  Nfit = number of fitting dimensions (1 or 2 in FIM)
  Nort = number of "orts" (2 in the default setup)

(assuming the null hypothesis that the time series consists of Nt samples of i.i.d. N(0,1) deviates).

[Answer last changed 28 Feb 2000]

---

Q53. What are some known problems with the AFNI package?
Alas, no nontrivial program is without bugs or other flaws. The ones that I know about are listed below.

• Plugins: The plugin startup code searches all the directories given in the environment variable AFNI_PLUGINPATH for plugin libraries. If this environment variable is not set, then the PATH variable will be used instead. The use of PATH has caused problems at 2 sites, for reasons unknown. Therefore, it is best to set AFNI_PLUGINPATH directly before starting the afni program. In the C shell:

    setenv AFNI_PLUGINPATH /plugin/directory
  

  In the Bourne or Korn shells

    AFNI_PLUGINPATH=/plugin/directory ; export AFNI_PLUGINPATH
  

  Logically, these go best in your startup files (e.g., .cshrc, .profile, etc.). You can also set environment variables in your .afnirc file; for details, see README.environment.

  Note that the Makefiles and binary distributions install the plugins in the same directory as the other AFNI binaries. If you wish to avoid trying to load plugins altogther, the switch -noplugins can be used on the afni command line. You may also set the environment variable AFNI_NOPLUGINS; this too will prevent the plugin startup code from being executed.

  Local Plugins: If you develop your own plugins (see /pub/dist/doc/afni_plugins.ps), you must be sure to compile them with the same Makefile that was used to compile the AFNI package. Otherwise they may not be loaded correctly. This problem has arisen with our SGI systems, which have several different binary execution modes (selected by compile-time options to cc), which are not compatible with each other (e.g., a -n32 module can't be mixed with a -64 module).

  Plugin Date Checking: When new versions of the package are released, I don't guarantee binary compatibility with older plugins. One reason is the need to add new data structures to the AFNI internals. The result is that all plugins and command line programs need to be recompiled with each release of AFNI. To remind you of this (if you are developing your own plugins), the plugin startup code checks the plugin compilation date vs. the AFNI compilation date - if the plugin is compiled before afni itself, a warning message will be displayed.

• FIM+ and 3dfim: As mentioned in Q35 and Q41, the internal FIM+ and batch program 3dfim don't calculate exactly the same % Change. They also don't prune the low-intensity voxels from the calculation in exactly the same fashion. There are probably other differences, as well, which are ultimately due to the different histories of these two codes.
• Byte Ordering: As discussed in Q18, AFNI now keeps a flag in each dataset header file noting the byte order of the information in the bricks. However, older (pre-May 1998) files won't have this flag. When transported between computer systems, such datasets will behave peculiarly. The solution is to properly mark old datasets with their byte order. The method for doing this is described in AFNI Necronomicon (README.environment).
• Illegal Float BRIKs: It is possible to write a set of bits to a floating point file that does not represent a legal number (this cannot happen with an integer-valued file). Floating point bricks are assumed to contain legal numbers, and AFNI programs will likely fail badly (e.g., go into an infinite loop) if this assumption is violated.

  There are two ways to avoid this problem:
  (1) Use program float_scan. It can read a floating point file, patch (set to zero) illegal values, and write them back to the disk file.
  (2) The environment variable AFNI_FLOATSCAN, if set, will check and patch input float .BRIK data when they are read into memory. Of course, this takes extra CPU time. It may also take extra memory or swap space, since patched data cannot be loaded by mmap(), but must be read directly into malloc()-ed RAM.

• SunOS 4.1.x: This ancient operating system (used mostly for hunting mastodons) is no longer supported, since I don't have easy access to one of these beasts any more. (Nor do I want to have such access - don't offer!)
• Solaris 2.5: /usr/dt/lib is not included in the default search path when a program starts. To force this directory to be searched for libraries at program runtime, you must set the environment variable LD_LIBRARY_PATH properly. Using the C shell:

    setenv LD_LIBRARY_PATH /usr/lib:/usr/dt/lib:/usr/openwin/lib:/usr/ucblib
  

  Using the Bourne or Korn shells:

    LD_LIBRARY_PATH=/usr/lib:/usr/dt/lib:/usr/openwin/lib:/usr/ucblib
    export LD_LIBRARY_PATH
  
  

  Again, these should go in your startup files (e.g., .cshrc) so that they are executed whenever you login.

  You will need to install all the Solaris 2.5 X11 and Motif patches to get AFNI to work without crashing.

• Solaris 2.x (for x > 5): See the latter part of the answer to Q29. Also, I have heard that the Rescan function in AFNI works very slowly under Solaris. Why, I don't know.

  I have no experience with Sun's latest release of Solaris (Solaris 7? 8?), so you are on your own there. Good hunting.

  [26 May 2000] The only Solaris machine I have access to has been upgraded to Solaris 2.8, so that is what the Solaris binaries are compiled for from now on.

  [07 Nov 2001] AFNI precompiled binaries for Solaris 2.x are now available here, for x=6 and x=8. There are still a few minor user interface glitches that surface on Solaris, but these are cosmetic blemishes.

  [22 Jul 2002] The Solaris 2.6 machine I used was upgraded to 2.8 recently, so Solaris 2.6 binaries and support will no longer be available.

• HP-UX: Under HP-VUE (or CDE), and when using an 8 bit PseudoColor X11 visual, you'll find that the window manager hogs all the colors to make the window decorations look nice. You have to reclaim some of these colors before AFNI will work. To do this, you click on the VUE control panel icon that is like a painter's palette. Under that application, choose Color (or something like that), and under that menu, choose Color Usage (or something like that). Then pick Medium or Low, instead of Default. (It may also be labeled Most Colors for Applications.) After that is done, you'll have to confirm it, and then logout and login to have this change take effect.

  On HP-UX systems, another problem is that HP seems to ship the Unix kernel configured so that each running program can only access 64 MB of RAM, no matter how much memory the system actually has. To fix this, the super-duper-user (root) has to use the SAM program (part of HP-UX) to adjust the kernel parameters, and then rebuild the operating system. You will probably want to have this done.

• CDE: The above remarks about color usage also apply to the Common Desktop Environment DeskTop (CDE DT), which is in fact adapted from HP-VUE.

  Another "feature" of CDE is that dropdown menus (as in the AFNI Lock and Misc menus) don't stay posted when the mouse button is released. This makes it difficult to click on a menu item such as a Toggle Button. I don't know how to make the menus stay up, but a workaround is to popup the menus with the right mouse button (Button 3) and, while holding Button 3 down, use Button 1 to activate the Toggle Button. This method requires a little practice, but developing these motor skills will provide a good neural workout for your next scanning session.

• SGI IRIX: Text entry fields don't show a vertical (I-beam) cursor, unlike other platforms. Apparently this is a bug (feature?) with SGI's Motif library. I have been unable to find a way around this problem. I don't know why software from SGI itself doesn't have this problem.

  The volume rendering plugin does not work properly at the higher optimization modes of the Volpack library. I don't know why this is, nor do I know how to fix the problem. My only suggestion is to switch to a Linux box. Rendering is pretty nice on a 1 GHz Athlon system with 1 GB of RAM!

• Linux/Intel: You will have to byte swap short (16-bit) images from most other workstation platforms. The program 2swap can do this for 2D and 3D data. Also, the 3Ds: input format can do this as the images are read in - see the output of to3d -help and Q12 for more information about how to swap bytes on input to to3d. The program 4swap can be used to quad-swap 32-bit image files; for example, files in IEEE floating point format. You can also swap the bytes from the interactive control panel in to3d, using the cleverly labeled Byte Swap button.

  AFNI itself now stores the byte order of datasets in the header files, and will swap bytes appropriately on input. This means that you don't have to swap the bytes in .BRIK files when you move them between systems. If you do want to swap the bytes (for efficiency), then run 2swap or 4swap (for short and float files, respectively) on the .BRIK files, and use program 3drefit to alter the byte order flag in the .HEAD files. See README.environment for a few more details.

  If you wish to force all newly created AFNI datasets to be stored in a particular byte order, you can do so using the environment variable AFNI_BYTEORDER. This may ease the problem of inter-system dataset transport. (But you will have to make sure that this variable is set on all systems/accounts which use AFNI.)

  Some desktop/window managers under Linux (e.g., KDE) don't respect the request that AFNI makes to keep the aspect ratio - width/height fraction - of the image windows constant. This makes it hard to properly resize an image. You can make AFNI enforce the aspect ratio constraint itself by setting the Unix environment variable AFNI_ENFORCE_ASPECT; details can be found in README.environment.

  Most pre-installed Linux systems now seem to ship with a 16-bit or 24-bit TrueColor X11 visual set as the default. AFNI will work with this imaging mode, but the older program FD2 will not (nor do I plan to make any changes to FD2 in the future - it is a pile of spaghetti code from multiple authors). As a lenitive (look it up!), AFNI has been modified to allow you to input image time series and look at their graphs as well as their images. This is the new [20 Oct 1999] -tim option - see the output of afni -help for usage details.
  [16 Oct 2001]: FD2 now works with TrueColor, thanks to Andrzej Jesmanowicz of MCW.

• IBM RS/6000: Plugins don't work, or so I was informed by the guy who gave me the Makefile for this type of system. Not having one meself, I have no real comment.

  [Answer last changed 24 Nov 1999]

---

Q54. Do you offer a course on using the AFNI package?
Not at this time. Some information about courses on how to do FMRI (including analysis) can be found here.

I have offered a course at the NIH on using AFNI. The handouts from this course can be found here. Of course, you won't get my inimitable jokes this way, but the material may be of some value despite this fact.

[Answer created 29 Sep 1999]

---

Q55. How does the Range setting interact with the color pbar scale?
Range is set on the Define Function control panel, at the bottom right. By default, the autoRange value is used, which is calculated from the Func overlay brick. You can set the Range value to anything you want, though, by toggling autoRange off and typing your desired value into the widget below.

The value of 1 on the color pbar corresponds to the Range setting. For example, if the Func is % Change, and Range is set to 5, then the pbar values are % Change relative to 5. That is, pbar=0.4 corresponds to % Change=2.

Note that you can change the top value on the pbar by using the hidden menu that pops up when you right-click (mouse button 3) on the Inten label at the top of the pbar. However, the Range value always maps to pbar=1.0, so if you set Range=1 and pbar top=5, then you will have the same effect as pbar top=1 and Range=5. See the file README.setup for more information about this popup menu.

The Range control is original to the earliest AFNI, but the ability to control the pbar scale is more recent, which explains why there are two ways to accomplish the same thing.

[Answer created 11 Oct 1999] - Also see Q22.

---

Q56. Why are my 3D+time datasets so huge when I resample them to Talairach coordinates?
This happens because the default resampling size in AFNI is 1 mm. This value was chosen because it is about the voxel size we use for T1-weighted anatomical background images, so resampling from +orig to +tlrc coordinates will look good on these images.

However, FMRI time series data are usually gathered at much coarser resolutions; typically, 3 mm on a voxel edge. In this case, resampling on the +tlrc grid at 1 mm resolution will expand the number of voxels by about a factor of 27 (only "about", because the total volume of the +tlrc grid may be less than or greater than the total volume of the +orig grid). In this case, you don't really need to resample your data to such a fine grid, since it doesn't have such high resolution information in it anyway. You can change the resampling grid size (always cubical; cf. Q28) using a control on the Define Datamode control panel.

[Answer created 11 Oct 1999]

---

Q57. How can I get an image from AFNI into a paint/drawing program?
Once you have made the image window look like what you want to see, the steps are:

1. Make sure the image window Save button says "Save:one". If necessay, open the Disp control sub-window and switch the save setting to "Save One". This will make the image saving function save the image (or montage) as it is shown on the screen.
2. Press Save:one. You will get a popup box that asks you for a filename prefix. Enter something; for example, Elvis. Then press the Set button on the popup box. This will write out the file in the format used by the netpbm package (either the PGM or PPM format, depending on if the image saved was grayscale or color). In the example, the filename would be Elvis.pnm.
3. Now you need to get the image into a format that your other software will like:
   • If you use the Unix+X11 program xpaint, it can read PGM/PPM (collectively called PNM format) images directly.
   • If you use a PC or MAC, a TIFF formatted file will usually work. (TIFF is not actually one format, but a family of formats. I usually use a LZW-compressed TIFF image to save disk space - most software that I use seems to be able to handle this TIFF sub-format.) Conversion can be done on Unix using the xv program (with a graphics interface, available here):
     1. Type the command: xv Elvis.pnm
     2. Click mouse button 3 in the xv image window - this will popup the xv control panel.
     3. Click on the Save button in the control panel. This will popup another control panel.
     4. At the top of the Save control panel, change the Format to TIFF. You may also want to change the output filename, which is entered at the bottom of the Save control panel. Then press the Ok button. You can then choose the compression type.

     The command line program pnmtotiff can also do the conversion from PNM to TIFF format. (This is part of the netpbm package - source code available at the AFNI distribution sites - which is often pre-installed on Linux systems.) The command to use would be something like

     
       pnmtotiff Elvis.pnm > Elvis.tif
     

   • Other netpbm conversion program that you might want to use include ppmtopcx and ppmtobmp, for converting to the PCX and BMP formats, respectively (in the latter case, you probably want to use the -windows option, since the default is to create an OS/2 format file!). All the netpbm programs come with Unix man pages, and most of them have -help options as well.
   • The convert program (part of the ImageMagick software package) can convert image files between a vast number of formats.
   • The gimp program, a Linux Photoshop-like drawing program, can also do image file conversion, as well as letting you draw on top of your images.

After the conversion, you will need to transport the file to the desired system, via a network, a floppy diskette, voudon chants, or whatever.

[29 Jun 2001] AFNI can now save images from the image viewing windows in a variety of formats, using external programs:

• JPG format (using program cjpeg)
• GIF format (using program ppmtogif)
• TIF format (using program ppm2tiff or pnmtotiff)
• BMP format (using program ppmtobmp)
• EPS format (using program pnmtops)
• PDF format (using programs pnmtops and epstopdf)
• PNG format (using program pnmtopng)

For AFNI to use them, these programs must be in your path when AFNI starts up. You can change the default save format using the Disp image viewer control panel, or by right-clicking (Button 3) on the image viewer Save: button.

• These programs are installed on many Linux distributions by default. Many of them are in the netpbm package, if you need to load them from CD or an online update service (e.g., Redhat, Mandrake, Debian).
• For Solaris, you can get precompiled binaries for these programs from http://sunfreeware.com/.
• For SGI IRIX, you can get precompiled binaries for these programs from http://freeware.sgi.com/index.html.
• For HP-UX, you can get precompiled binaries for these programs from http://hpux.cs.utah.edu/.
• For Mac OS X, you can get precompiled binaries for these programs from http://fink.sourceforge.net/ (but you have to install the Fink package to manage the process).

If you want to make an animated GIF from a collection of images, see Q26. If you want to search for a place to get some of the above programs, try Google.

[Answer created 12 Oct 1999, per the suggest of MSB; edited 29 Jun 2001]

---

Q58. What good is the "Anatomy Parent" in to3d?
For most purposes, you don't need to specify an anatomy parent dataset when you create a new dataset. The anatomy parent is the dataset that provides the master transformation when creating "follower" datasets. That is, the anatomy parent is the dataset that is marked and transformed to Talairach coordinates and that corresponds to the alignment of the other datasets for which it is the parent. The transformation from +orig to +tlrc coordinates in the anatomy parent is applied to the other datasets to produce their +tlrc versions - these are the followers.

The way that AFNI was intended to be used is that all the datasets from a single scanning session would be stored in a separate directory (a "session directory"). These datasets are presumed to be aligned with one another. When you mark and transform one of them, it is assigned to be the anatomy parent of the other datasets in that directory.

Note This Carefully:
If you stored datasets from multiple sessions in the same directory, AFNI won't know which marked/transformed dataset is the correct anatomy parent to use for which unmarked datasets. For example, if you have scanned two people, Fred and Ethel, you might have the following datasets:

  ethel.anat+orig    ethel.anat+acpc    ethel.anat+tlrc
  ethel.func+orig
  fred.anat+orig     fred.anat+acpc     fred.anat+tlrc
  fred.func+orig

To create the follower datasets ethel.func+tlrc and fred.func+tlrc, a geometrical transformation from +orig coordinates to +tlrc coordinates must be used. In the absence of other information, AFNI will use the transformation present in the first marked dataset it finds - in this example, ethel.anat+orig. This will produce a good ethel.func+tlrc, but fred.func+tlrc will be wrong. The usual symptom of this is that the functional overlay will not be in the proper place when you are viewing the fred datasets and switch between the +orig and +tlrc views.

You can fix this problem by assigning the correct anatomy parent datasets. This can be done at dataset creation time with to3d, or it can be done later using the -apar option of program 3drefit (this option was added 14 Oct 1999). In the case of Fred and Ethel, the correct command lines would be

  3drefit -apar fred.anat+orig fred.func+orig
  3drefit -apar ethel.anat+orig ethel.func+orig

If you were to run AFNI after these fixes had been made, then the derived dataset fred.func+tlrc should now be computed correctly.

Note that if you use program adwarp to compute follower datasets, then you are required to give the anatomy parent on the command line, and so the problem discussed here shouldn't arise (assuming you use the correct dataset for the parent!).

I have heard that some people think that when AFNI is used to write out a functional dataset in Talairach coordinates, the current Anat dataset is used to master the coordinate transformation. This assumption is incorrect! The anatomy parent of the functional dataset is used; if one was not assigned by the user (via to3d or 3drefit), then the first anatomical dataset with a transformation in each directory will be chosen as the anatomy parent for all "orphan" datasets in that directory. This means that when combining multiple scanning sessions, even of the same subject, in the same directory, you must be careful to set the anatomy parents correctly. Otherwise, you will get incorrect transformations to Talairach coordinates applied to some of your functional datasets.

As of 03 Dec 1999, AFNI now prints a warning when a dataset is "forcibly adopted" to have an anat parent. This warning is issued when (a) the dataset does not have an anat parent encoded into its header file, and (b) there is more than one anatomical dataset with Talairach markers in the same directory.

As of 15 Dec 1999, most AFNI programs that create a dataset from another dataset (e.g., the "3d" codes) will make the anat parent ID of the output dataset be the same as the anat parent ID of input dataset. If this relationship needs to be altered, this can be done using 3drefit.

When a dataset has an anat parent ID encoded in its header, the interactive AFNI program will attempt to match the dataset to its anat parent at startup. If it cannot make the match, a warning message will be printed. This is the only program that actually uses the anatomy parent encoded in the dataset header (at this time), since it is the only program that reads in a whole library of datasets. The other program that uses the anatomy parent idea is adwarp, but that program requires input of the chosen anatomy parent on the command line - it will ignore the anatomy parent ID in dataset headers.

[Answer added 14 Oct 1999; edited 16 Dec 1999]

---

Q59. Are the Talairach coordinates from AFNI the same as from SPM?
Not exactly. AFNI tries to follow the 1988 Talairach-Tournoux Atlas as far as possible. This was requested by the FMRI researchers at MCW back in 1994 (when AFNI was born). This is why the program requires you to choose the superior margin of the AC, rather than the center, since that is what the Atlas does. This is why you pick the brain bounding-box points after alignment to the AC-PC axis, since that alignment defines the anterior-posterior, superior-inferior, and right-left axes. This is why 12 sub-volumes are used to define the transformation, rather than using a single affine mapping for the whole brain volume.

Most other software, including SPM, does a single affine transform for the entire brain (a simpler alternative), or does a high dimensional nonlinear transformation (a much more complex alternative). A description of how SPM and the MNI software packages do the T-T transformation can be found here. Because they use a different "standard brain" than the Talairach-Tournoux atlas, their transformation is scaled somewhat differently. The differences in coordinates can be as much as 10 mm, apparently.

My goal in AFNI was to allow the user to set the T-T transformation within an accuracy of about 4 mm. Since the RMS 3D inter-subject distance fluctuations in cortical landmarks is about 6-7 mm, I felt that this was accurate enough. This does not allow for systematic bias between the somewhat different definitions and transformations used by the many programs out there. I'm not aware of any systematic comparison of the T-T transformation packages.

Coordinate Order:
By default, AFNI programs report spatial coordinates in DICOM order:

  -x = Right      +x = Left
  -y = Anterior   +y = Posterior
  -z = Inferior   +z = Superior

This system is referred to as RAI in the AFNI documentation, since x=Right-to-Left, y=Anterior-to-Posterior, and z=Inferior-to-Superior. SPM reports coordinates in the LPI coordinate order; that is:

x_SPM = -x_AFNI y_SPM = -y_AFNI z_SPM = +z_AFNI

In +tlrc and +acpc coordinates, the origin of coordinates is the anterior commissure; in +orig coordinates, the origin of coordinates is wherever you put it when creating the dataset with to3d.

To get the SPM coordinates order reported from AFNI (in the upper left of the controller windows) and 3dclust (in the output table of cluster coordinates), you can either run these programs with the command line option "-orient LPI", or set the environment variable AFNI_ORIENT to the string LPI.

[Answer added 19 Oct 1999; edited 02 Jan 2002]

---

Q60. How many sites use AFNI?
I don't know. Since you can download it freely, you can use it without telling me. I used to require registration - at the point when I stopped doing that, I had over 200 registration forms accumulated. But this is just a count of people who downloaded the software - this doesn't say that they actually found it useful. My guess is that 30-50 places currently use AFNI for some purpose. This is based on the number of people that ask me questions (via e-mail or via the AFNI Message Board), and on the number of downloads recorded by the Web server after I post announcements of upgrades. But this is a crude guess, and I have no way of assessing its variance in the probability space of guesses about AFNI usage.

A list of all papers that I know of which cite AFNI can be found here. I suppose that the institutions that so publish can be taken as a list of places that use AFNI seriously.

[Answer added 25 Oct 1999]

---

Q61. How can I mask off "function" outside the brain?
There is no direct way to do this within the interactive AFNI program itself, once the function has been created.

Before the function is created with the interactive FIM, you could set the background threshold suppression, externally using the environment variable AFNI_FIM_BKTHR, or internally using the sub-menu item FIM->Edit Ideal->Bkg Thresh in an AFNI graphing window. This sets the threshold for the elimination of the background voxels during the interactive FIM calculations. The average intensity of all voxels in the first 3D volume used in the correlation is calculated. Voxels with intensity below 0.01 * AFNI_FIM_BKTHR * (this average) will not have the correlation computed. The default value of AFNI_FIM_BKTHR is 10.0, but values as large as 50.0 may be useful (I use 40.0 myself).

After the function is created, the only way to make it disappear in undesired regions is to set it to zero in the dataset .BRIK. This can be done by creating a mask dataset at the functional resolution; the mask is nonzero in the brain and zero outside the brain. You could make such a mask in at least 2 different ways:

• Use 3dmerge -1clip to create a 1 brick dataset that has only the desired voxels. For example

    3dmerge -1clip 100 -prefix z100 -1dindex 5 ztime+orig
  

  This will zero out voxels below 100 from sub-brick #5 of dataset ztime+orig, and write the resulting 1 brick dataset into z100+orig. You can look at this new dataset inside AFNI, and use the "Choose Zero Color" feature of the image viewer to see exactly which voxels are zero (cf. Q9). How you choose the clipping level (100 in the example) is up to you.
• Alternatively, you can use 3dIntracranial on a T1-weighted high-resolution anatomy to create a high-resolution dataset that only contains the brain. Then you use program 3dfractionize to make a mask dataset from this at the EPI spatial resolution.

  It is also possible to use 3dIntracranial directly on a single sub-brick dataset created from an EPI time series. When you do this, you'll probably have to directly use the -min_val and -max_val options to set the initial clipping thresholds. This range of values can be determined by a quick look at the image data - set -min_val to a dim value at the edge of the brain and set -max_val to a bright value in the center of the brain. (Q11 shows how to find the numerical value stored in a voxel.)

  The resulting dataset can be used as mask dataset in programs like 3dmaskave, etc. You can also use it with 3dcalc, as described below.

Once you have the mask dataset (e.g., z100+orig), then you can use it to modify the EPI time series itself, or to modify the FIM dataset. This is done using program 3dcalc, using a command like:

  3dcalc -a ztime+orig -b z100+orig -expr 'step(b)*a' -prefix ztime100

This will multiply every voxel in the 3D+time dataset (symbol 'a') times 0 if the mask dataset (symbol 'b') is <= 0, and times 1 if the mask dataset is > 0. A similar command could be used to modify the FIM dataset instead.

If you want to use the first mask creation method outlined above, this could be done in one step with 3dcalc. To apply it to a FIM dataset, for example:

  3dcalc -a zfunc+orig -b 'ztime+orig[5]' -expr 'step(b-100)*a' -prefix zfunc100

This extracts sub-brick #5 of ztime+orig as symbol 'b', and uses it as a mask directly. Since the datasets used in 3dcalc must be at the same resolution, it isn't possible to use the output of 3dIntracranial directly here - that is the purpose of 3dfractionize.

Mask datasets have other uses. They can be used to extract voxel values from other datasets for import into spreadsheets (say), or to get averages over regions-of-interest (cf. Q30). Masks can be created by software, as in the examples above, or can be created/edited manually using the Draw Dataset plugin.

[13 Nov 2001]:
You can also create a brain-only mask from an EPI dataset using a combination of the programs 3dClipLevel and 3dcalc.

Program 3dClipLevel examines a dataset and attempts to find a voxel value that can be used as an intensity threshold to exclude "small" values. For example:

  3dClipLevel r1:time+orig
  330

The number "330" is the output of the program. Then the command

  3dcalc -a 'r1:time+orig[0]' -prefix r1mask -datum byte -nscale -expr 'step(a-330)'

will create a dataset that is zero where the input is <=330 and 1 otherwise. A way to do this in a script (so you don't have to see and retype the output of 3dClipLevel) is:

  set val = `3dClipLevel r1:time+orig[20]`
  3dcalc -a 'r1:time+orig[0]' -prefix r1mask -datum byte -nscale -expr "step(a-$val)"

3dClipLevel works by following this empirically derived recipe:

1. Set the initial clip level to include 65% of all positive voxels.
2. Find the median of all positive values >= current clip value.
3. Set the clip value to 0.50 of this median.
4. Loop back to steps 2 and 3 until the clip value doesn't change.

To see the progress of the iterations, use the "-verb" option on the command line. This procedure seems to work pretty well on the EPI datasets that I've used. It probably won't work well on datasets gathered with local coils or with pulse sequences that have "weird" contrasts.

[29 Apr 2002]:
New program 3dAutomask combines the above operations. It is an easy way to create a brain-only mask from an EPI dataset.

[Answer modified 29 Apr 2002]

---

Q62. How can I add my own function to the FIM+ menu?
Read the comments at the top of the source code file afni_fimfunc.c.

Basically, you have to write a C function that takes as input a time series array from a single voxel and returns as output 1 or more numbers to be stored for that voxel. Two sample functions are in that file (for the Spearman rank and quadrant correlations - "robust" versions of the cross-product correlation computed by the normal FIM options).

Then you have to "register" the function with AFNI. The sample functions are registered from within afni.c itself. You can embed your functions in a plugin, and register them from within the plugins initialization routine. Or you can give them to me to re-distribute with the rest of the AFNI package.

[Answer added 02 Feb 2000]

---

Q63. How can I read ASCII image files into to3d?
A new command line format has been added that allows you to read in one or more 2D images from an unstructured file of ASCII numbers. The purpose of this feature is to make it easy to read values output from some non-AFNI analysis programs.

On the to3d command line, the form of the ASCII image specifier is one of the following:

• 3As:nx:ny:nz:fname - meaning to read shorts
• 3Ab:nx:ny:nz:fname - meaning to read bytes
• 3Af:nx:ny:nz:fname - meaning to read floats

The format is like the 3D: format (cf. Q12) without the header-skip parameters, where

• nx = x-dimension of image(s) to be read
• ny = y-dimension of image(s) to be read
• nz = number of images to be read
• fname = filename from which to read images

Lines in the file that start with a "#" character will be skipped. All the numbers read from the file (left-to-right, then line-by-line) will be divided into sets of size nx*ny, each of which makes up an image. The numbers are all read in floating point format and should be separated by blanks, end-of-lines, or other "whitespace" characters. (Commas will be treated like spaces.)

The values read in are later converted (for 3As: and 3Ab:) into the commanded output type. Note that this conversion could introduce errors; for example, a value of 100,000 in a file read with 3As: would be beyond the upper limit of shorts (32,767) and will probably wrap back to -31,072 (100,000-2*65536).

Consider reading the following file with a 3As:2:3:2 format:

 1 2 3 4 5
 6 7
 8 9 10 11 12

The resulting 2 images would be

 Image #1     Image #2        --> x-axis
 1 2           7  8          |
 3 4           9 10          v
 5 6          11 12         y-axis

There should be exactly nx*ny*nz values read from fname. If there are too few values in the file, the final images will be filled out with zeros; if there are too many values in the file, the final values from the file won't be used. In either case, a warning message is printed to stderr.

ASCII is not a good or efficient file format for storing large 2D or 3D images. Not only does it take up a lot of disk space, it is slow to read.

[Answer added 10 Feb 2000]

---

Q64. What is "Warp on Demand"?
When AFNI was first created (1994), it took 1-2 minutes to compute a transformed 3D brick after the Talairach transformation was computed, on the computers we had available then. This is not interactive, and consumes a lot of disk space, so I developed the "warp-on-demand" method of viewing transformed datasets - only the slices needed for displaying the images were computed. As a result, you can look at datasets in the Talairach view without actually writing them out to disk in that coordinate system.

At the top of the Define Datamode control panel, there are two toggle buttons:

  View Anat Data Brick
  Warp Anat on Demand

If the BRIK file for the current anatomical dataset exists for the current view (e.g., +tlrc), then both of these buttons will be enabled. In this case, you can toggle between viewing image data drawn directly from the +tlrc.BRIK file (the top option) and viewing data transformed (i.e., warped) from the +orig.BRIK file (the bottom option). However, if the +tlrc.BRIK file doesn't exist for the current anat dataset, then only the bottom option is possible.

Now, if you switch to Talairach view when the current anat dataset doesn't have a +tlrc.BRIK file, then Warp Anat on Demand will be forcibly set. When you switch to an anat dataset that does have a +tlrc.BRIK file, View Anat Data Brick will be enabled, but it will not be engaged - that is, the previous mode (Warp Anat on Demand) will be still turned on.

On the other hand, when you switch to an anat dataset that has a +tlrc.BRIK file first (in +orig view), then switch to the +tlrc view, the mode View Anat Data Brick is never disengaged, since it is still possible to view the dataset directly from its BRIK data in this coordinate system.

This is a little confusing, and since the action is often hidden away on the Define Datamode panel, it is not obvious what is happening. To palliate this confusion, AFNI now shows the string {warp} in window titlebars when Warp Anat on Demand is turned on.

AFNI has been modified to allow the user to specify that View Brick should be enabled whenever possible after switching datasets. This is done by setting the new environment variable AFNI_VIEW_ANAT_BRICK (to anything). This can be done in the .afnirc file, or the .cshrc file, or at the command line. See README.environment for more details.

[Answer added 16 Mar 2000]

---

Q65. How can I use scripts to change datasets in the volume rendering plugin?
When a script (.rset file) is saved, the underlay/overlay dataset names and ID codes are stored. The Alter Dsets? toggle on the Scripts menu tells the plugin to use the ID codes to change the datasets loaded into the renderer.

You could use this feature to render many different datasets the same way as follows:

1. Render one dataset the way you want. Then save the script for that one image with Save This, say into file fred.rset.
2. Edit fred.rset. For each dataset to render, add a set of lines like so to the end:

     ***RENDER
       dset_idc = MCW_BVVWWLEGIDC       // to change the underlay
       func_dset_idc = MCW_BVVWWLEGIDC  // to change the overlay
   

   The dataset ID codes for a collection of datasets can be found with a command like

     3dinfo *+tlrc.HEAD | grep Identifier
   

3. Read & Exec file fred.rset, after turning Alter Dsets? on (and maybe Alter Grafs?). If all goes well, you'll get the set of renderings you want in the renderer image display window.

For more information on the format of .rset script files, see README.render_scripts.

On a Related Subject
The underlay dataset clipping values are not alterable using the Automate feature. They are changeable by scripts, though. If you want to render a dataset with a lot of different clipping values, you can do so by altering the cliptop and/or clipbot script variables.

[Answer added 13 Apr 2000]

---

Q66. How can I figure out the format an image file is in?
First, read the answer to Q12 to understand how to input general image files to AFNI programs.

Second, most MR images come in power-of-2 sizes (64, 128, 256 are common), and most are square. So the images are most likely 64x64, 128x128, or 256x256. They are most likely either shorts (if from the scanner) or floats (if from a post-processing program). In most cases, the image data is at the end of the file, and the extra information is at the beginning (if there is any extra information).

So, if you know nothing about the file except its size in bytes (which ls -al fname would give you), then some exploration is needed. An example: I was recently given some files of length 137216 bytes (each). I was told they had 64x64 images in them. So I looked at one such file with the command

  afni -im 3D:-1:0:64:64:16:fname

Why did I pick nz=16? Because this is the maximum number of 64x64 short images that can fit into a file with 137216 bytes (137216/8192 = 16.75). I used the Sagittal image viewer to look at the images. The images looked like junk, but there was some hint of structure in some of them. So I thought they might be 128x128 images, and quit AFNI to try

  afni -im 3D:-1:0:128:128:4:fname

Again, the images were junk, but they definitely had more structure - they looked like every other scan line was messed up, but alternate ones were OK-ish. So I next tried

  afni -im 3D:-1:0:256:256:1:fname

and got nice 256x256 images, but each of which was really an array of 16 64x64 images. Now I got it - each image file was really 16 packed-together images. AFNI doesn't have a way to read such images directly. Instead, I used the imcutup program to cut each image file apart into its constituent sub-images, and then was able to assemble the sub-image files using to3d. (New program imcutup [09 May 2000] is for breaking up sets of images that have been arranged into a 2D layout. The 3D: format can't read these, since it requires that all the data for one 2D slice be contiguous in the file. That is, 3D: can deal with 1D arrays of 2D images, but imcutup is for dealing with 2D arrays of 2D images.)
[Later] I found out that this 2D array of small images, stored as one image, was a Siemens Vision .ima file. Since then, I've modified to3d to be able to read these files directly, without use of 3D: or imcutup.

In recent another case, I received a file of size 17047952 bytes, with intimations that it contained 2080 64x64 images of shorts. So I looked at it with

  afni -im 3D:0:0:64:64:2080:fname

since this input format was what the sender was using in to3d. I discovered that the first image was garbage. Then I calculated 2*64*64*2080=17039360, and so discovered there were 8592 extra bytes in the file. I assumed these were header data, and so tried

  afni -im 3D:-1:0:64:64:2080:fname

and then got a nice set of images. Viewing them let me determine there were 208 images from each of 10 slices, with all the images from slice #1 first, then all the images from slice #2, and so on. So the correct way to run to3d was

  to3d -time:tz 208 10 1.5s alt+z 3D:-1:0:64:64:2080:fname

There are only a smallish number of possibilities. If these trials had failed, I might have tried byte-swapping, or reading the data as floats. Usually 5-10 minutes of messing around can find the format of a file, especially if you have some information upon which to base your sleuthing.

DICOM Files [by MS Beauchamp of the NIMH]
DICOM files consist of a header plus raw image data. Usually, only a single slice is contained in each file. We instruct to3d to read the raw image data (located at the end of the file) and skip the header information, using the -1 global offset in the 3D: file specifier.

A simple example: we have collected a scan series with 100 time points (TR=2 seconds), where each time point is a volume containing 20 slices (collected in the order 1,3,5...), and each slice has resolution 64x64. The DICOM format files in this example are named t001sl01,t001sl02,..t001sl20,t002sl01,..t002sl20,..t100sl01,..t100sl20. Assuming the data in these files are stored as shorts (the most usual case), the correct command line would be

  to3d -time:zt 20 100 2000 alt+z '3D:-1:0:64:64:1:t*sl*'

Detailed explanation of each command line component:

• -time:zt => images as listed on the command line are in order by slice number, then by time
  (slice number is spatial order, not acquisition order!)
• 20 => number of "z" points (number of slices)
• 100 => number of "t" points (number of time points)
• 2000 => TR (default unit is milliseconds)
• alt+z => order of slice acquisition
• 3D: => the images are shorts
  • -1: => to3d will calculate the header length
  • 0: => no additional header
  • 64: => number of in-plane voxels in the x dimension
  • 64: => number of in-plane voxels in the y dimension
  • 1: => number of slices in each file
  • t*sl* => the wildcard that gives the names of all the image files

One problem with using DICOM is the name that the manufacturer assigns to the files (I don't believe this is part of the DICOM specification itself). to3d relies on the command line order of the files to specify the space-time sequencing of the images. (To see the command line ordering of the files in the example above, one would type the Unix command ls t*sl*.) I have seen DICOM files where the correct ordering of the files was a code embedded deep in the middle of the filename. Other information was at the front of the filename. As a result, the command line ordering of the filenames had nothing to do with the spatiotemporal ordering of the data. When this problem arises, it is necessary to rename the files so that their command line ordering becomes the same as their spatiotemporal ordering. How you do this depends on the exact details of the filenames. One renaming method is discussed here.

[Answer added 09 May 2000; edited 26 Jul 2000]

---

Q67. How can I compare 'small' and 'big' Talairach box datasets?
This question arises when people have a bunch of older datasets that were transformed to Talairach-Tournoux space when the transformed box only extended to z=-55 mm. In March 1996, I extended the 3D grid of the +tlrc datasets to z=-65 mm - the reason for this was that for many subjects, the z=-55 mm level did not get the whole cerebellum. To maintain backward compatibility, the Big Talairach Box? toggle box was added to the Markers control panel. If this toggle is turned off, then the old z=-55 mm lower limit is used; otherwise, the new z=-65 mm is used.

The "best" solution is to go back and retransform the old datasets to the Big box. This is a fair amount of trouble, though. If you don't care about activation in that very inferior region, then you can extend the old (small box) datasets to have the same size as the new (Big box) datasets using the program 3dZeropad. This will add slices of all zeros, which will make the dataset .BRIK files the same size, and thus be able to be compared (e.g., via 3dANOVA).

If you have used the default 1 mm voxel size in +tlrc coordinates (as almost everyone does), then you need to add 10 zero slices at the inferior edge of the small box datasets. You can do this with a command like

   3dZeropad -I 10 -prefix fredBig fredSmall+tlrc

The new dataset (fredBig+tlrc) is what you want. If you used some other voxel size, then you'll have to figure out the amount of zero padding yourself (hint: use 3dinfo).

[03 Oct 2000] You can now use the new Dset Zeropad plugin to do the same thing interactively.

[Answer added 11 Jul 2000 - edited 03 Oct 2000]

---

Q68. How can I do SPM-like analyses with AFNI?
Whereas Talairach normalization is often a relatively late step in an AFNI analysis (after time series analysis like cross-correlation), it is a very early step in SPM analysis (before time series analysis). To replicate this in AFNI, follow the following steps:

1. Talairach normalize an anatomical dataset in the subject working directory
2. Write out a normalized version of the echo-planar (functional) 3D+time BRIKs for each subject using the Write Anat button in the Define Datamode control panel (you must be in Talairach View to write out Talairach BRIKs). The default resampling resolution of 1 mm will create enormous disk files, so be sure to use a resolution closer to the actual resolution of your 3D+time functional data (typically about 4 mm).
3. Analyze the normalized time series data using multiple linear regression, deconvolution, ROI averaging, etc.

[Answer added 26 July 2000 (by MSB)]

---

Q69. I'm losing data when I use the "Nudge" plugin on functional datasets!?
Each dataset is defined over a 3D rectangular volume. When you nudge it, some data will be shifted out of that volume and will be lost. (Conversely, data that "comes in from outside" will be zero.)

This is particularly visible when nudging functional overlays atop an anatomical underlay, which is usually defined over a larger 3D volume than the functional dataset. To avoid this problem, you can use the 3dZeropad program (or the Dset Zeropad plugin) to pad the outside of the functional dataset with planes of zeros. Then the functional dataset will be defined over a larger volume, and small shifts won't send the nonzero data outside of this volume.

An alternative would be to nudge the anatomical dataset to be aligned with the functional. This might be better, since the usual 3D whole-head images have plenty of slop space around them. If you do this in +orig coordinates (the only logical place), you should do it before you do Talairach markers, since their coordinates are not altered by the nudge -- as a result, they will no longer overlay the correct anatomical locations.

[Answer added 03 Oct 2000]

---

Q70. How do I register data from the same subject taken on different days?
This is actually mildly complicated, since you need to deal with the possibility that the anatomical coverage of your functional slices between days may not completely overlap. The file README.registration describes in detail the AFNI approach to this problem. A partial summary is given below, but you must read the full documentation to do this properly.

If you have high resolution anatomical datasets from each day, then you can use 3dvolreg to register the anatomicals to a common base. 3dvolreg will report the rotation+shift used for this registration. You can then use the same parameters to run 3drotate to move the functional data to the base coordinates. (This is assuming the functional data is aligned with the anatomicals from the same day.)

Alignment of anatomicals is done with a command like this:

   3dvolreg -twopass -twodup -heptic -clipit -rotcom -verbose -verbose \
            -prefix S3.2nd.REG -base 'S3.1st+orig[0]' S3.2nd+orig

where the parameters chosen mean

• -twopass means to use a coarse registration pass followed by the usual fine registration pass;
• -twodup means to duplicate the 3D (x,y,z) origin of the base dataset into the output dataset;
• -heptic -clipit defines the interpolation algorithm (when potentially moving images a long ways, the default -Fourier interpolation methods can cause wraparound from opposite edges);
• -rotcom means to print out, at the end, the command to use with 3drotate to get the same effect as 3dvolreg; the output of the -rotcom option is something like:

  
     3drotate -heptic -clipit -rotate 2.338I -2.451R 0.985A -ashift 3.265S 2.476L 6.670P
  

  This fragment can be used to generate the correct commands for moving other datasets that are aligned with the input dataset to be aligned with the base dataset;
• -verbose -verbose means to print out a lot of information about the progress of the program (this is optional);
• -prefix S3.2nd.REG sets the prefix of the output dataset;
• -base 'S3.1st+orig[0]' sets the base brick (the goal is to move the input dataset brick to match this);
• S3.2nd+orig is the input dataset.

When registering high resolution anatomicals, a couple of problems may arise:

• Noise around the edges, particularly at the inferior edge of the head, may make it hard to get a good match between the input and base datasets. This can be overcome by using the -edging option to 3dvolreg. This option instructs the program to ignore a layer of voxels around the edge of each 3D brick. The default edging is 5% of each dimension.
• If the images are gathered with a local gradient coil (as is used at MCW), the region near the base of the brain may be geometrically distorted. This is because the gradient fields are no longer linear in space there. With such data, registration by 3D rigid rotation+shift is not capable of producing perfect alignment, since the two volumes are warped relative to each other. In this case, the best you can do is to increase the edging factor, so as to make the registration depend only on the images in the regions without distortion, and then live with the results in the distorted regions. The alternative is to get an image reconstruction program that takes into account the nonlinear distortion of the gradient fields, and corrects for this effect. Of course, this is easier said than done.

For these reasons, it is essential that you visually inspect the results of the registration before relying on it!

Please note that registering high resolution anatomicals is a very intensive computation; for example, 256x256x124 volumes uses 330+ MB of memory and 150-300 CPU seconds on a 600 MHz Pentium III machine. Don't try this on some wimpy machine!

[Answer added 10 Dec 2000, edited 04 Mar 2001]

---

Q71. How can I edit the History Note in a dataset?
This might be desirable because you have included some subject-identifying information in the History Note, but now want to distribute that file to others without such data being included. The Dataset Notes plugin does not allow you to edit the History Note. There are two ways to change this Note:

• You can entirely replace the History Note using the -HH option to command-line program 3dNotes.
• If you want to edit the dataset .HEAD file, you can edit the History Note. Look for the attribute named HISTORY_NOTE. You can edit the string that follows. Note that the string must start with the single forward quote character ' and end with the tilde character ~. Ends-of-line are stored as the character combination \n. The number of characters in the string, not counting the ' but counting the ~, must be correctly stored in the count field of the HISTORY_NOTE attribute. Otherwise, the .HEAD file will be unreadable. (If you want to try this, make a backup copy of the .HEAD file first!)

I am unlikely to make this an easier task. It shouldn't be simple to tamper with the historical record.

---

Q72. Can I use AFNI or its code at my company?
Yes. AFNI is released under the GPL - see README.copyright for the details. There are no restrictions on use of AFNI within the company (or other institution).

If you use the code in something that is later released by your company (say, an image display function in a product), then your company must be willing to redistribute the source code for that part of the product which incorporates the AFNI-derived code (read the GPL for details). This may not be to your company's liking, to put it mildly. So you may want to be careful from the start, if you are actually using pieces of the code in your own hack jobs - you never know what may migrate into a "product".

[Answer added 04 Mar 2001]

---

Q73. What is Resampling?
When resampling data to a new grid (e.g., going from +orig to +tlrc), it is necessary to interpolate between the data values given on the input grid to calculate values on the output grid. NN (nearest neighbor) and Li (linear) are two ways to get these output values. In 2 dimensions:

    A---------B
    |         |  A,B,C,D are values at 4 voxels in original grid
    |         |
    |         |
    |  x      |  x is value in output grid that we need to compute
    C---------D  given the values A,B,C,D and given the location of x

With NN interpolation, x = C, since C is closest to x.

With Li interpolation, x = 0.7*(0.8*C+0.2*A) + 0.3*(0.8*D+0.2*B).
The numerical factors are chosen from the fact that x is 30% of the way from left to right (so the left edge gets 70% of the weight and the right edge gets 30%), and is 20% of the way from bottom to top (so the bottom edge gets 80% of the weight and the top edge gets 20% of the weight).

If A=B=C=D, then both values of x will be the same. Otherwise, they will be different. Suppose you have a mask that is 1 inside the brain and 0 outside. In the center of the brain, all values are 1, so NN and Li resampling will give the same results; outside, all values are 0, so again NN and Li will be identical. But at the edges of the brain, there will be some x outputs that straddle some 0's and some 1's. NN will always produce x=0 or x=1 in this case (depending on what value is physically closest to the location of x). Li will produce some value between 0 and 1; NN and Li will not be identical at the brain surface. If you subtracted a NN-interpolated and Li-interpolated mask, the NN-Li mask will be 0 inside the brain and outside the brain, and there will be a thin outline of nonzero values at the brain surface.

For masks, the lesson is always use NN. This is because the input values come from a discrete set, and only NN resampling will ensure that the output values stay within that discrete set. For functional and/or anatomical values, the choice is less clear, since the input values come from a continuous set (all real numbers, say). My usual choice is to use NN for functional data and Li for anatomical data. The reason for this choice is that I feel it is a little "funny" to interpolate statistical parameters (such as a correlation coefficient).

[Answer added 23 May 2001]

---

Q74. How can I normalize the sub-bricks in a 3D+time dataset?
"Normalizing" refers to modifying the voxel values in a sub-brick in some way, using the mean value from the entire sub-brick. This is often done in PET data analysis, to allow for different doses of the radioactive pharmaceutical. If you want to do something like this in FMRI (why?), then one way is to combine 3dmaskave and 3dcalc:

  3dmaskave -q tset+orig > tset_vbar.1D
  3dcalc -a tset+orig -b tset_vbar.1D -expr "a/b" -prefix tset_norm

The first operation computes the mean of each sub-brick in the 3D+time dataset tset+orig and saves these numbers into a 1D timeseries file. The second operation divides each voxel by the mean of its sub-brick (you could replace that by subtraction, if you like), and saves the result into a new dataset.

Although the name 3dmaskave seems to imply that you need to use a mask, that is not in fact true -- if you don't supply a mask, then the statistic is calculated over the entire sub-brick.

In 3dcalc, if you supply a .1D file instead of a dataset, then the program treats that as a 3D+time dataset with the n^th sub-brick voxel values all being set to the n^th value in the 1D timeseries.

[Answer added 23 May 2001]

---

Q75. How can I extract a voxel timeseries to a text file?
From the AFNI graph window, you can use the menu item Opt->Write Center to write the central sub-graph's data to a file. This file will be named something like 001_002_003.1D, where 001 is the x-axis voxel index (sometimes called I), 002 is the y-axis voxel index (J), and 003 is the z-axis voxel index (K). These voxel indexes are shown in the lower-right corner of the graph window. They can also be shown in the AFNI controller window if you turn on the Datamode->Misc->Voxel Coords toggle.

If you want to extract the data from the command line (perhaps in a script), you can do something like this:

  3dmaskdump -cmask "-a dset+orig[0] -expr rect(i-1)*rect(j-2)*rect(k-3)" -noijk dset+orig > qtemp
  1dtranspose qtemp 001_002_003.1D
  /bin/rm qtemp

The first line uses the -cmask feature of 3dmaskdump to compute a mask "on-the-fly", in this case a mask that is nonzero only at the single voxel (I,J,K)=(1,2,3). The output is sent to file qtemp. This will consist of all the data in a single line. The utility program 1dtranspose is used to tranpose this to a .1D format file (a single column), and then qtemp is deleted.

[Answer added 23 May 2001]

---

Q76. After 3dZeropad-ing, where are the Talairach markers?
Most operations (including 3dZeropad) that operate on one dataset and produce another do not preserve the existence of markers from the input to the output dataset. This was a deliberate decision. You can add an empty set of markers to a +orig dataset using the command

  3drefit -markers anat+orig

[Answer added 23 May 2001]

---

Q77. How can I take a mask from +tlrc/+acpc back to +orig?
Some people prefer to create mask datasets in +acpc coordinates, where the brain is in a standard alignment. But later they want to apply these masks to EPI datasets in the +orig coordinate system. This can be done with the 3dfractionize program. The method would be something like this:

  3dfractionize -template anat+orig -input mask+acpc -warp anat+acpc -prefix mask -clip 0.05 -vote

where anat+orig is the original anatomical dataset, anat+acpc is the transformation of that dataset to AC-PC aligned coordinates, and mask+acpc is the mask dataset you created (drawn atop anat+acpc, presumably). This command will produce mask+orig, where voxels in the +orig grid that are at least 5% occupied by nonzero voxels in the +acpc grid will get their values from mask+acpc.

[Answer added 23 May 2001]

---

Q78. How can I remove a subject's name from an image file?
If you plan to distribute scanner-derived image files, you probably should remove the subject's name from the file headers. To find out if the name is in the files, try something like this:

   strings 347-2-99.ima | more

Here, strings is a standard Unix command that will print legible ASCII strings from the input file, and 347-2-99.ima is a sample image file name. Here is some of the output from this sample:

   SIEMENS
   MGH-NMR Center
   ekit5mrc
   Cox
   MAGNETOM Allegra
   808c3e52
   VC
   Robert Cox
   051Y
   K1.3.12.2.1107.5.2.7.20006.20010516081058000

In this example, we see that the subject's name (which has been replaced with my name) appears in two different forms: as the whole string "Robert Cox" and as the surname "Cox".

To fix this, the AFNI package program strblast can be used. In this example, we need to run the program twice, in order to remove the two different identifier strings:

   strblast 'Robert Cox' 347-2-99.ima
   strblast 'Cox' 347-2-99.ima

However, you probably want to do this to many different files. This can be done by using a wildcard to specify the filename:

   strblast 'Robert Cox' *.ima
   strblast 'Cox' *.ima

On some computers (e.g., SGIs), the number of files specified by a wildcard is limited. You may get a warning like "command line too long". Don't panic: strblast can do the wildcard expansion for you. You need to put the filename with the wildcard inside single forward quotes, as in

   strblast 'Robert Cox' '*.ima'

Do not use double quotes "*.ima" or backward single quotes `*.ima` for this purpose! Also, if there are any blanks or other "special" characters in the target string, it need to be enclosed in single quotes, as in the examples above. (It wasn't necessary to put 'Cox' into single quotes, but it doesn't hurt.)

AFNI .BRIK files contain only the image data from the image files, and so do not contain any of the header strings that might identify a subject. If you put a subject's name into the .HEAD file using the Notes facility, then you can remove it by editing the Note (using the "Dataset Notes" plugin or the 3dNotes program).

Warning: program strblast will overwrite the existing file(s). To make sure it doesn't harm your image files, you should make a copy of one first, play with strblast on it, then see if it is still readable (e.g., using a command like afni -im filename and opening a Sagittal image viewer).

[Answer added 29 Jun 2001]

---

Q79. How to Render a Slanted Slab?
Perhaps you are considering doing an FMRI experiment with slanted (oblique) slices, and wish to determine if a slice package of a certain thickness will cover the anatomical region of interest. You can use the AFNI volume renderer to display such a slanted slab. The central trick is to use the Expr > 0 Cutout to define the slab. The steps are

1. Get your anatomical dataset into the necessary orientation for the renderer (if it isn't already, see FAQ #47).

2. Open the renderer, select the anatomical dataset as the Underlay.

3. Set Cutouts to 1; set the #1 cutout to Expr > 0.

4. You now have to enter a mathematical expression that defines the region inside the slab, based on its coordinates. In the coordinate system used by AFNI, +x=Left, +y=Posterior, and +z=Superior. For an oblique coronal/axial slab, this is tilted about the x-axis by some angle "a". The figure below illustrates the geometry:

   
   
   

   The set of points within the slab is described by the inequality
   abs(y*cos(a)-z*sin(a)-s) < w/2
   for angle="a", slab center offset="s", and slab width="w". To render a slanted coronal slab 30 mm thick, tilted posteriorly by 25 degrees, we could use this for the cutout expression:
   abs(y*cosd(25)-z*sind(25)-20)-15
   where the "sind()" and "cosd()" functions take arguments in degrees, and where I have chosen the offset to be 20 mm (you will have to alter this to get the exact position you want). Below, the renderer controls and resulting rendered image are shown.

   
   
   

5. The above is for slanting in the yz-plane: for obliques that are between coronal and axial. If you want obliques that are between coronal and sagittal, then you are slanting in the xy-plane, and the roles of (y,z) in the above discussion are replaced by (x,y) respectively. Similarly, if you want obliques that are between axial and sagittal, then you are slanting in the xz-plane, and the roles of (y,z) in the above discussion should be replaced by (x,z) respectively.

6. If you want "double obliques", then you'll have to figure out the expression yourself. In such a case, I suggest studying up on 3D orthogonal matrices.

[Answer added 27 Aug 2001]

---

Q80. What is the format of the TTatlas+tlrc dataset?
This dataset stores the Talairach Daemon database, as implemented into AFNI. A detailed description of its format is given here.

[Answer added 25 Oct 2001]

---

Q81. Can I send you some data?
That can be arranged. I'll need some e-mail explaining why you want to send data. The full instructions can be found at the bottom of the AFNI Message Board.

[Answer added 03 Nov 2001]

---

---

---

Q999. What are your pet peeves about FMRI?

1. Abbreviating "Functional Magnetic Resonance Imaging" as "fMRI" rather than "FMRI".
2. Referring to the analysis of functional image data as "functional analysis" (which is an entirely separate branch of mathematics over 80 years old).
3. People who don't ever read the manuals, README.* files, or use the "BHelp" feature in AFNI, but instead bug me with questions like, "What does this button here do?" (that is to say, virtually everyone).
4. The sentence, "I have a quick question" (particularly when uttered by anyone whose initials are PAB).

Note also that the choice of number for this question implies that eventually I'll run into the "FAQ 1K" problem, which will probably grind all civilization to a halt. Otherwise, note that AFNI is perforce Y2K compliant, since it only uses Unix date functions (which means that in the year 2037 or so, trouble may arise - if problems show up then, please contact me at my nursing home - I'll be the one saying, "When I was a kid, we'd never analyze brain data that way ...").

Ciao - Bob Cox
[last update to this file: 29 Apr 2002]