
    ***** 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
