***** Welcome to the world of MCW AFNI, version 2.23 ***** ***** Robert W. Cox, Medical College of Wisconsin ***** ***** August 1999 ***** DOCUMENTATION ------------- The documentation for MCW AFNI is in the following files: afni200.ps = User documentation for the AFNI program itself. afni_aux.ps = User documentation for MCW AFNI auxiliary programs. afni_plugins.ps = Programmer documentation for writing "plugins" to extend the capabilities of AFNI. FD2.ps = User documentation for the older program FD2. README = This file. README.changes = Additions to the package since manuals were written. README.copyright = The Copyright of MCW AFNI. README.* = Other documentation files about specific issues. The *.ps files are PostScript. If you do not have a PostScript printer, then the freeware programs Ghostscript and Ghostview will enable you to display the documents on the screen and format them for output to other types of printers. See the WWW site http://www.cs.wisc.edu/~ghost/index.html for more information about the Ghostscript and Ghostview programs. The PostScript files are no longer included in the base distribution, afni98.tgz, but are in the file afnidoc.tgz. This change is due to their ever-growing size. The file afni_aux.ps contains documentation for almost all of the command line programs included in the AFNI package. There are also individual .ps files for each of these programs. ARCHIVES -------- AFNI files are tar-ed and gzip-ed archives. If you don't have GNU gzip, you will find the archive for gzip on the computer system whence you got the AFNI distribution. To make the executable file 'gzip', the following commands should suffice: tar xf gzip.tar cd gzip-1.2.4 -- follow the instructions in the INSTALL file The archive file with the source code for AFNI and its associated programs is afni98.tgz. To uncompress this, the following commands should work: gzip -dc afni98.tgz | tar xf - cd ./AFNI98 -- follow the instructions in the README file (e.g., these instructions) The PostScript documentation is unpacked with gzip -dc afnidoc.tgz | tar xf - -- files are in subdirectory AFNIDOC/ For some platforms (those which we have easily available at MCW), binaries are available in the binaries/ subdirectory at the distribution site. COMPILATION ----------- To compile AFNI, you will have to choose a Makefile. Some of the versions in the distribution file are filename target system compiler ------------- --------------- ----------------------- Makefile.hpux* HP 7000/8000 series HP compiler, HP Motif Makefile.sgi* SGI IRIX systems SGI compiler, SGI Motif Makefile.linux* Linux GCC compiler, Red Hat Motif Makefile.solaris26_gcc Solaris 2.6 GCC compiler, Sun Motif Makefile.rs6000 IBM RS/6000 IBM compiler, IBM Motif Makefile.osf1 DEC Alpha OSF/1 GCC compiler (The hpux and sgi Makefiles come in slightly different versions for the different versions of IRIX and the different cpu classes. The linux Makefiles are for different versions of Red Hat - _rh52 is for version 5.2 and _rh60 is for version 6.0. Not all the possibilities are represented here -- just those to which I have easy access in Milwaukee.) You will undoubtedly need to alter the INSTALLDIR macro in the Makefile before you compile. The flags for the C compiler and loader likely need to be changed before anything useful can be done, unless you are compiling on a system virtually identical to one we have at MCW. Once you have figured this part out (what fun!), then the commands cp Makefile.whatever Makefile make totality Note that the IBM RS/6000 Makefile does not include plugin support, since I don't have regular access to such systems. I believe that these systems are similar to SGI systems in this regards. (The only system that I know of which is different is HP-UX.) Note also that the "models" routines and "nlfit" programs require that plugins be compiled. To get the plugin code to run correctly on a new type of system, you must edit the file "machdep.h" appropriately, and probably know a fair amount of detail about your operating system. GENERAL WOES ------------ 1) 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). If you wish to avoid trying to load plugins altogther, the new 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. The file README.environment contains documentation on all the Unix environment variables that AFNI uses. 2) If you develop your own plugins (see 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). 3) AFNI requires that the X11 graphics server be set up to have a "PseudoColor" default Visual. (The X11 program xdpyinfo can be used to find out what the default setup is.) If your default is set to "TrueColor", AFNI will not work. The mechanism for changing the default varies between operating systems. ** 22 Aug 1998: AFNI now supports the use of TrueColor Visuals, the other major form of bit-pattern-to-color mapping in X11. At this time, the implementation of TrueColor in AFNI is experimental, and probably has undiscovered flaws. The pre-AFNI program "FD2" does not work with TrueColor. AFNI still uses the default X11 Visual for all its display purposes (i.e., you can't instruct the program to use another Visual). 4) As far as I know, only SGI supports the use of 12 bit PseudoColor Visuals in X11; all other X11 servers only support 8 bits in PseudoColor. AFNI will use about 130 colors when it runs. On an 8 bit system, this is over half of all possible color cells. In such a case, AFNI may not run if other programs are already using most of the color cells. Notorious offenders are Netscape and the CDE default color setup. Netscape can "install" its own colormap if it is run with the command "netscape -install". AFNI also has a "-install" switch, if you want to try it. WOES and GOOD NEWS: Sun ----------------------- You may need to install some patches from Sun for X11 and Motif to get AFNI to run reliably on your Solaris system. Solaris 2.5 and above now ship with Motif. The libraries are stored in the directory /usr/dt/lib. By changing IFLAGS and LFLAGS appropriately in the Makefile, you should be able to compile and run the afni and to3d programs. (Assuming you have the ANSI C compiler, of course.) Makefile.sparc5_2.5 or Makefile.solaris26_gcc will probably work for you. /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/dt/lib:/usr/openwin/lib:/usr/ucblib Using the Bourne or Korn shells: LD_LIBRARY_PATH=/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. Alternatively, Makefile.sparc5_2.5 is set up to record the use of the /usr/dt/lib directory at runtime, using the -R option to the compiler. If you use this feature of the Makefile, then it shouldn't be necessary to set the LD_LIBRARY_PATH variable (although it wouldn't hurt). Some problems with Solaris 2.6 seem to be fixed with some patches described in source code file "machdep.h". You may need one or both of these for this operating system. Another problem arises with Solaris 2.5 (SunOS 5.5). In this case, you might need to link to the UC Berkely compatibility libraries. This is done by making the following changes in Makefile.sunultra (or whatever you choose to use): IFLAGS = -I. -I/usr/dt/include -I/usr/openwin/include -I/usr/ucbinclude LFLAGS = -s -L. -L/usr/dt/lib -L/usr/openwin/lib -L/usr/ucblib EXTRA_LIBS = -lsocket -lnsl -lgen -lucb -ldl PLFLAGS = -L. -L/usr/dt/lib -L/usr/openwin/lib -L/usr/ucblib This may cause some other problems, which is why it was removed. In particular, it makes the file selection tool unusable -- but this is only used from the "Read" buttons on the "Define Datamode" panel, so this may not bother you. All this is because Sun chose to develop a routine to read the list of filenames from a directory that is 1) different from almost every other Unix vendor (who instead chose to copy the UC Berkeley standard), AND ALSO 2) has the same subroutine name so that programs written for UCB compatible systems will compile but will not execute properly. Not having a Sun workstation, I don't have the resources to try to find a clean fix around this set of problems. WOES: Hewlett Packard --------------------- If you are using an HP workstation and HP-UX 9.0x, you should be aware that older versions of the HP ANSI C compiler have bugs at the higher optimization levels. You will need to upgrade your compiler. To find out what compiler revision you have, use the command strings /bin/cc | grep "HP C" You should be at revision A.09.73 (at least). For more details, see http://hpux.cae.wisc.edu/pubdomain/ANSI_C.html http://support.mayfield.hp.com/slx/html/ptc_hpux.html If you cannot upgrade your compiler easily, you should change the +O3 compiler switch in Makefile.hp to +O2. Under HP-VUE (or CDE), 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 "HP-VUE Color Usage". Then pick "Medium" or "Low", instead of "Default". After that is done, you'll have to confirm it, and then logout and login to have this change take effect. WOES: Common Desktop Environment -------------------------------- 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" is that the default action is that dropdown menus (as in the AFNI 'Lock' menu) don't stay posted when the mouse button is released. This makes it difficult to click on an item such as a Toggle Button (as in the AFNI 'Lock' menu). 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. WOES: Silicon Graphics ---------------------- Text entry fields don't show a vertical (I-beam) cursor, unlike other platforms. Apparently this is a bug (or a 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 doesn't have this problem. Some old versions of the SGI X11 server (Xsgi) don't seem to discard their garbage very well. This can lead to consumption of huge quantities of memory over time. The solution is to forcibly restart the server every time you log out. This can be done by setting the "terminateServer" resource to "True" in file /var/X11/xdm/xdm-config. (Only the superuser can do this.) The SGI compiler on the R5000 processor sometimes core dumps at optimization -O3. That's why Makefile.sgi5k* uses -O2. 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. On our machines, 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.) WOES: Linux ----------- You will have to byte swap short 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' for more details. ** May 1998: AFNI now stores the byte order of datasets in the header files, and will swap bytes appropriately on input. See file README.environment for a few more details. ... Later in May: I just now remembered to update the sample datasets on the ftp site, so that they should display correctly without byte swapping. If you 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). SAMPLE DATASETS --------------- The file sample.tgz has a pair of sample datasets, one anatomical and one functional. You can use this to try AFNI out, and see if it is useful for your purposes before you go to the trouble to put your data into the program's 3D format. To uncompress and run: gzip -dc sample.tgz | tar xf - afni sample The anatomical dataset has the markers already set for the transformation to stereotaxic coordinates. This may help you learn to find the commissures and the other anatomical landmarks that need to be marked. However, you will certainly need to get some guidance from a neuroanatomy textbook in order to become adept at marking the required locations. The file sample96.tgz has some sample 3D+time datasets. This file is huge (20 Megabytes), so you will probably be happier if you download it at night or on a weekend (considering the congestion on the Internet). MISCELLANY ---------- The manual and the sample dataset should get you started. Don't forget the 'BHelp' feature, either: it will give you a few lines of reminder about any given item in the AFNI and to3d interfaces. Also, every program accepts the command line option "-help", which will display some information about how to use the software. In some cases (e.g., 3dmerge), this -help information is quite lengthy. Image file formats are described in the auxiliary programs manual. The '3D:' formats should allow you to input almost any uncompressed data file. Note that it is possible to set up the Unix environment to recognize certain file sizes as containing images of pre-specified dimensions -- this is described in the '3D:' section of the auxiliary programs manual. I'm interested in bug reports. However, if you have problems on a particular system that we don't have in the Biophysics Research Institute at MCW, I may not be able to say anything useful. I'm also interested in reports of success in getting AFNI to run on other systems than those listed earlier (especially in Makefiles and in changes needed to machdep.h), and in reports of success in using AFNI to analyze FMRI datasets. AFNI is a big package with lots of features. If you are just getting started in FMRI, you will probably want to use the FD2 and fim2 programs first, to deal with 2D+time data. After you are comfortable with that, you can move up to the more complex world of 3D and 3D+time datasets. When you do that, you will find that you need a lot of disk space to store your data. For example, a 3D data volume in Talairach coordinates, resampled at 1 mm resolution, takes up over 8 Mbytes of space. It is easy to gather hundreds of such data volumes. Storing and processing this much data will occupy a good workstation. At MCW, we have 15 workstations and 150 Gbytes of disk space devoted to processing FMRI data -- and it isn't enough. The "netpbm" package of image utilities is very useful. It is also available on the MCW AFNI distribution computer, in the same directory. This software is not written here, but by many people from around the world. The "Save:" button in AFNI saves images to disk in the PNM format, which can then be converted to TIFF, GIF, etc., using utilities in netpbm (or using the wonderful shareware program "xv"). There is a link to the Web pages made for AFNI on my home page, given below. REFERENCES ---------- If you wish to refer to AFNI in a publication, please use this article: RW Cox. AFNI: Software for analysis and visualization of functional magnetic resonance neuroimages. Computers and Biomedical Research, 29:162-173, 1996. A later article that has some information about AFNI is RW Cox and JS Hyde. Software tools for analysis and visualization of FMRI Data. NMR in Biomedicine, 10:171-178, 1997. PostScript preprints of these two papers are on the Web site for AFNI. A number of software tools for FMRI (including AFNI) are reviewed in S Gold, B Christian, S Arndt, G Zeien, T Cizadlo, DL Johnson, M Flaum, and NC Andreasen. Functional MRI statistical software packages: a comparative analysis. Human Brain Mapping, 6:73-84, 1998 ============================================================================= Robert W. Cox, PhD Associate Professor and Graduate Program Director Biophysics Research Institute / Medical College of Wisconsin Voice: 414-456-4038 / Fax: 414-456-6512 / mailto:rwcox@mcw.edu http://varda.biophysics.mcw.edu/~cox/index.html