Unix Environment Variables Used by AFNI
=======================================
The AFNI program allows you to use several Unix environment variables
to influence its behavior.  The mechanics of setting an environment
variable depend on which shell you are using.  To set an environment
variable named "FRED" to the string "Elvis":

   csh or tcsh:  setenv FRED Elvis
   bash or ksh:  FRED=Elvis ; export FRED

Normally, these commands would go in your .cshrc or .profile files,
so that they would be invoked when you login.  If in doubt, consult
your local Unix guru.  If you don't have one, well....

You don't NEED to set any of these variables -- AFNI will still work
correctly.  But they are an easy way to set up certain defaults to
make AFNI a little easier on your neocortex and hippocampus.

N.B.: Changes to environment variables AFTER you start a program will
      not be seen by that program, since each running program gets
      a private copy of the entire set of environment variables when
      it starts.  This is a standard Unix feature, and is not specific
      to AFNI.  Some variables can be set internally in AFNI using
      the "Edit Environment" control from the "Datamode->Misc" menu
      or from the image window Button-3 popup menu.  Such variables
      are marked with "(editable)" in the descriptions below.

N.B.: Some variables below are described as being of "YES/NO" type.
      This means that they should either be set to the value "YES"
      or to the value "NO".

N.B.: You can now set environment variables on the 'afni' command
      line; for example:
        afni -DAFNI_EDGIZE_OVERLAY=YES -DAFNI_SESSTRAIL=3
      This may be useful for a 'one time' situation, or as an alias.
      You can also use this '-Dname=val' option in 1dplot and 3dDeconvolve.
      -- RWCox - 22 Mar 2005
      And now you can use this feature on most program command lines.
      -- RWCox - 13 Dec 2007

N.B.: At the end of this file is a list of several environment variables
      that affect the program 3dDeconvolve, rather than the interactive
      AFNI program itself.

N.B.: If you set an AFNI environment variable on the command line, or
      in a shell startup file (e.g., ~/.cshrc), and also have that
      variable in your ~/.afnirc file, you will get a warning telling
      you that the value in the ~/.afnirc file is being ignored.
      To turn off these warnings, set environment variable
      AFNI_ENVIRON_WARNINGS to NO.

********************************************************
June 1999: Setting environment variables in file .afnirc
********************************************************
You can now set environment variables for an interactive AFNI run in the
setup (.afnirc) file.  This is provided as a convenience.  An example:

***ENVIRONMENT
  AFNI_HINTS = YES
  AFNI_SESSTRAIL = 3

Note that the spaces around the "=" sign are required.  See README.setup
for more information about the possible contents of .afnirc besides the
environment variables.

A few other programs in the AFNI package also read the ***ENVIRONMENT
section of the .afnirc file.  This is needed so that environment settings
that affect those programs (e.g., AFNI_COMPRESSOR for auto-compression of
output datasets) can be properly initialized in .afnirc.

At the same time, the routine in AFNI that initializes certain internal
constants from X11 resources (usually in your .Xdefaults or .Xresources
file, and described in file AFNI.Xdefaults) has been modified to also
allow the same constants to be set from Unix environment variables.
For example, the gap (in pixels) between sub-graphs is set by the
X11 resource "AFNI*graph_ggap", and can now be set by the environment
variables "AFNI_graph_ggap" or "AFNI_GRAPH_GGAP", as in

  AFNI_graph_ggap = 6   // this is a comment

If an X11 resource is actually set, it will take priority over the
environment variable.  Some of the variables that can be set in this
way are:

 AFNI_ncolors             = number of gray levels to use
 AFNI_gamma               = gamma correction for image intensities
 AFNI_graph_boxes_thick   = 0=thin lines, 1=thick lines, for graph boxes
 AFNI_graph_grid_thick    = ditto for the graph vertical grid lines
 AFNI_graph_data_thick    = ditto for the data graphs
 AFNI_graph_ideal_thick   = ditto for the ideal graphs
 AFNI_graph_ort_thick     = ditto for the ort graphs
 AFNI_graph_dplot_thick   = ditto for the dplot graphs
 AFNI_graph_ggap          = initial spacing between graph boxes
 AFNI_graph_matrix        = initial number of sub-graphs
 AFNI_fim_polort          = polynomial detrending order for FIM
 AFNI_fim_ignore          = how many pts to ignore at start when doing FIM
 AFNI_montage_periodic    = True allows periodic montage wraparound
 AFNI_purge               = True allows automatic dataset memory purge
 AFNI_resam_vox           = dimension of voxel (mm) for resampled datasets
 AFNI_resam_anat          = One of NN, Li, Cu, Bk for Anat resampling mode
 AFNI_resam_func          = ditto for Func resampling mode
 AFNI_resam_thr           = ditto for Threshold resampling mode
 AFNI_pbar_posfunc        = True will start color pbar as all positive
 AFNI_pbar_sgn_pane_count = # of panes to start signed color pbar with
 AFNI_pbar_pos_pane_count = # of panes to start positive color pbar with

Some other such variables are described in file AFNI.Xdefaults.  Note that
values that actually affect the way the X11/Motif interface appears, such as
AFNI*troughColor, must be set via the X11 mechanism and cannot be set using
Unix environment variables.  This is because they are interpreted by the
Motif graphics library when it starts and not by any actual AFNI code.

The following example is from my own .afnirc file on the Linux system on
which I do most of the AFNI development.  The first ones (in lower case)
are described in AFNI.Xdefaults.  The later ones (all upper case) are
documented in this file.  (You can tell from this file that I like to
have things line up.  You would never be able to tell this from the
piles of paper in my office, though.)

 ***ENVIRONMENT

 AFNI_ncolors             = 60      // number of gray levels
 AFNI_gamma               = 1.5     // adjust for proper display
 AFNI_purge               = True    // purge datasets from memory when not used
 AFNI_chooser_doubleclick = Apply   // like Apply button; could also be Set
 AFNI_chooser_listmax     = 25      // max nonscrolling items in chooser lists
 AFNI_graph_width         = 512     // initial width of graph window (pixels)
 AFNI_graph_height        = 384     // initial height of graph window
 AFNI_graph_data_thick    = 1       // graph time series with thick lines
 AFNI_fim_ignore          = 2       // default value for FIM ignore
 AFNI_graph_ggap          = 7       // gap between sub-graphs (pixels)
 AFNI_pbar_hide           = True    // hide color pbar when it changes size
 AFNI_hotcolor            = Violet  // color to use on Done and Set buttons
 AFNI_SESSTRAIL           = 2       // see below for these ...
 AFNI_RENDER_ANGLE_DELTA  = 4.0     //                       |
 AFNI_RENDER_CUTOUT_DELTA = 4.0     //                       |
 AFNI_FIM_BKTHR           = 25.0    //                       |
 AFNI_SPLASHTIME          = 3.0     //                       v

------------------------------------
Variable: AFNI_DONT_SORT_ENVIRONMENT
------------------------------------
If this YES/NO variable is YES, then the Edit Environment controls will
NOT be sorted alphabetically.  The default action is to sort them
alphabetically.  If they are unsorted, the editable environment variables
will appear in the control panel in the order in which they were added to
the code (that is, in an order that makes no real sense).

---------------------
Variable: AFNI_ORIENT (editable)
---------------------
This is a string used to control the display of coordinates in the AFNI
main control window.  The string must be 3 letters, one each from the
pairs {R,L} {A,P} {I,S}.  The first letter in the string gives the
orientation of the x-axis, the second the orientation of the y-axis,
the third the z-axis:

   R = right-to-left           L = left-to-right
   A = anterior-to-posterior   P = posterior-to-anterior
   I = inferior-to-superior    S = superior-to-inferior

If AFNI_ORIENT is undefined, the default is RAI.  This is the order
used by DICOM, and means

   the -x axis is Right,    the +x axis is Left,
   the -y axis is Anterior, the +y axis is Posterior,
   the -z axis is Inferior, the +z axis is Superior.

As a special case, using the code 'flipped' is equivalent to 'LPI',
which is the orientation used in many neuroscience journals.

This variable is also recognized by program 3dclust, which will report
the cluster coordinates in the (x,y,z) order given by AFNI_ORIENT.
Both AFNI and 3dclust also recognize the command line switch
"-orient string", where string is a 3 letter code that can be used
to override the value of AFNI_ORIENT.

The plugin "Coord Order" (plug_coord.c) allows you to interactively
change the orientation of the variable display within AFNI.

-------------------------
Variable: AFNI_PLUGINPATH
-------------------------
This variable should be the directory in which AFNI should search
for plugins.  If there is more than one appropriate directory, they
can be separated by colons, as in

   setenv AFNI_PLUGINPATH /directory/one:/directory/two

If this variable is not set, then AFNI will use the PATH variable
instead.  This will waste time, since most directories in the PATH
will not have plugins.  On some systems, using the PATH has been
known to cause problems when AFNI starts.  I believe this is due to
bugs in the system library routines (e.g., dlopen) used to manage
dynamically loaded shared objects.

------------------------
Variable: AFNI_NOPLUGINS
------------------------
If this YES/NO variable is set to YES, then AFNI will not try to
read plugins when it starts up.  The command line switch "-noplugins"
will have the same effect.

--------------------------
Variable: AFNI_YESPLUGOUTS
--------------------------
If this YES/NO variable is set to YES, then AFNI will try to listen
for plugouts when it starts.  The command line switch "-yesplugouts"
will have the same effect.  (Plugouts are an experimental feature
that allow external programs to exchange data with AFNI.)  It is now
also possible to start plugout listening from the Datamode->Misc menu.

---------------------
Variable: AFNI_TSPATH
---------------------
This variable should be set to any directory which you want to have
AFNI scan for timeseries files (*.1D -- see the AFNI manual).  If
more than one directory is desired, then colons can be used to
separate them, as in AFNI_PLUGINPATH.  Note that timeseries files
are read from all session directories, so directories provided by
AFNI_TSPATH are designed to contain extra timeseries files that
you want loaded no matter what AFNI sessions and datasets are being
viewed.

------------------------
Variable: AFNI_MODELPATH
------------------------
This variable should be set to the directory from which you want AFNI
timeseries models to be loaded.  These models are similar to plugins,
and are used by programs 3dNLfim, 3dTSgen, and the plugin plug_nlfit
(menu label "NLfit & NLerr") -- see documentation file 3dNLfim.ps.
If AFNI_MODELPATH is not given, then AFNI_PLUGINPATH will be used
instead.

-----------------------------------------
Variable: AFNI_IMSIZE_* (or MCW_IMSIZE_*)
-----------------------------------------
These variables (named AFNI_IMSIZE_1 to AFNI_IMSIZE_99) allow you
to control how the AFNI programs read binary image files.  The use of
these is somewhat complicated, and is explained in detail at the end
of the auxiliary programs manual (afni_aux.ps), in the section on "3D:"
file specifications, and is also explained in the AFNI FAQ list.

------------------------
Variable: AFNI_SESSTRAIL (editable)
------------------------
This variable controls the number of directory levels shown when
choosing between session directories with the "Switch Session"
button.  This variable should be set to a nonnegative integer.
If a session directory name were
   this/is/a/directory/name/
then the "Switch Session" chooser would display the following:

   AFNI_SESSTRAIL    Display
   --------------    -------
            0        name/
            1        directory/name/
            2        a/directory/name/
            3        is/a/directory/name/
            4        this/is/a/directory/name/

That is, AFNI_SESSTRAIL determines how many trailing levels of
the directory name are used for the display.  If AFNI_SESSTRAIL
is not set, then it is equivalent to setting it to 0 (which
was the old method).

--------------------
Variable: AFNI_HINTS
--------------------
This is a string controlling whether or not the popup "hints" are
displayed when AFNI starts.  If the string is "NO", then the hints
are disabled when AFNI starts, otherwise they are enabled.  In
either case, they can be turned off and on interactively from the
Define Datamode->Misc menu.

Hints can be permanently disabled by setting the C macro
DONT_USE_HINTS in machdep.h and recompiling AFNI.  They can also
be disabled at runtime by setting AFNI_HINTS to "KILL".

-------------------------
Variable: AFNI_COMPRESSOR (cf. AFNI_AUTOGZIP) (editable)
-------------------------
This variable is used to control automatic compression of .BRIK files on
output.  The legal values are "COMPRESS", "GZIP", and "BZIP2", which
respectively invoke programs "compress", "gzip", and "bzip2" (the program
must be in your path for compression to work).  If AFNI_COMPRESSOR is
equal to one of these, then all AFNI programs will automatically pass
.BRIK data through the appropriate compression program as it is written
to disk.  Note that this will slow down dataset write operations.  Note
also that compressed datasets cannot be mapped directly from disk into
memory ('mmap'), but must occupy actual memory (RAM) and swap space.  For
more details, see file README.compression.

Note that compressed (.BRIK.Z, .BRIK.gz, and .BRIK.bz2) datasets will
automatically be uncompressed on input, no matter what the setting of
this variable.  AFNI_COMPRESSOR only controls how the datasets are
written.

------------------------
Variable: AFNI_BYTEORDER
------------------------
This variable is used to control the byte order for output files.
If you use it, the two legal values are "LSB_FIRST" and "MSB_FIRST".
If you don't use it, the default order on your CPU will be used.
The main purpose of this would be if you were using a mixture of
CPU types reading shared disks (i.e., using NFS).  If the majority
of the systems were MSB_FIRST (e.g., SGI, HP, Sun), but there were
a few LSB_FIRST systems (e.g., Intel, DEC Alpha), then you might
want to do 'setenv AFNI_BYTEORDER MSB_FIRST' on all of the MSB_FIRST
systems to make sure that the datasets that they write out are
readable by the other computers.

Note that AFNI programs can now check the .HEAD file for the byte
order of a dataset, and will swap the bytes on input, if needed.
If you wish to mark all of the datasets on a given system as
being in a particular order, the following command should work:

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

Here, '/top/dir' is the name of the top level directory under
which you wish to search for AFNI datasets.  The string NATIVE_ORDER
means to set all datasets to the CPU default order, which is probably
what you are using now.  (You can use the program 'byteorder' to
find out the native byte ordering of your CPU.)

------------------------------
Variable: AFNI_BYTEORDER_INPUT
------------------------------
This variable is used to control the byte order for input files.
If you use it, the two legal values are "LSB_FIRST" and "MSB_FIRST".
The value of this variable is only used for old datasets that do
not have the byte order encoded in their headers.  If this variable
is not present, then the CPU native byte order is used.  If this
variable is present, and its value differs from the native byte
order, then 2 byte dataset BRIKs (short) are 2-swapped (as in
"ab" -> "ba") when they are read from disk, and 4 byte datasets
(float, complex) are 4-swapped ("abcd" -> "dcba").

[per the request of John Koger]

---------------------
Variable: AFNI_NOMMAP
---------------------
This YES/NO variable can be used to turn off the mmap feature by which
AFNI can load datasets into memory using the map-file-to-memory
functionality of Unix.  (Dataset .BRIK files will only be mmap-ed if
they are not compressed and are in the native byte order of the CPU.)
On some systems, mmap doesn't seem to work very well (e.g., Linux kernel
version 1.2.13).  You can disable mmap by 'setenv AFNI_NOMMAP YES'.

The penalty for disabling mmap is that all datasets must be loaded
into actual RAM.  AFNI does not have the ability to load a dataset
only partially, so if a 20 Megabyte .BRIK file is accessed, all of
it will be loaded into RAM.  With mmap, the Unix operating system will
decide how much of the file to load.  In this way, it is possible to
deal with more files than you have swap space on your computer
(since .BRIK files are mmap-ed in readonly mode).

The moral of the story: buy more memory, it's cheap.  At the time
I write this line [Aug 1998], I have a PC with 384 MB of RAM, and
it is great to use with AFNI.

[Feb 2004] I now have a Mac G5 with 8 GB of RAM, and it is even greater!

----------------------
Variable: AFNI_PSPRINT (editable)
----------------------
This variable is used to define a command that will print the
standard input (stdin) to a PostScript printer.  If it is defined,
the "->printer" button on the timeseries "Plot" windows will work.
For some Unix systems, the following should work:
  setenv AFNI_PSPRINT "lp -"
For others, this may work
  setenv AFNI_PSPRINT "lpr -"
It all depends on the printer software setup you have.  To send the
output into GhostView
  setenv AFNI_PSPRINT "ghostview -landscape -"

In the (very far distant) future, other windows (e.g., image and graph
displays) may get the ability to print to a PostScript file or printer.

---------------------------
Variable: AFNI_LEFT_IS_LEFT (editable)
---------------------------
Setting this YES/NO variable to YES tells AFNI to display images with
the left side of the subject on the left side of the window.  The default
mode is to display the right side of the subject on the left side of
the window - the radiology convention.  This "handedness" can also be
controlled with the "-flipim" and "-noflipim" command line options to AFNI.

--------------------------
Variable: AFNI_ALWAYS_LOCK
--------------------------
Setting this YES/NO variable to YES tells AFNI to start up with all
the controller windows locked together.  If you mostly use multiple
controllers to view datasets in unison, then this will be useful.
Notice that the Time Lock feature is not automatically enabled
by this -- you must still actuate it manually from the Lock menu
on the Define Datamode panel.

------------------------
Variables: AFNI_RENDER_* (editable)
------------------------
These variables set some defaults in the "Render Dataset" (volume
rendering) plugin.  The first two variables are

  AFNI_RENDER_ANGLE_DELTA  = stepsize for viewing angles, in degrees
  AFNI_RENDER_CUTOUT_DELTA = stepsize for cutout dimensions, in mm

These stepsizes control how much the control parameters change when
one of their up- or down-arrows is pressed.  Both of these stepsize
values default to 5.0.

The third variable is

  AFNI_RENDER_PRECALC_MODE = "Low", "Medium", or "High"

This is used to set the initial precalculation mode for the renderer
(this mode can be altered interactively, unlike the stepsizes).

The fourth variable is

  AFNI_RENDER_SHOWTHRU_FAC = some number between 0.0 and 1.0

This is used to control the way in which the "ShowThru" Color Opacity
option renders images.  See the rendering plugin Help window for more
information.

-------------------------
Variable: AFNI_NOREALPATH
-------------------------
Normally, when AFNI reads a list of session directories, it converts
their names to the "real path" form, which follows symbolic links, and
removes '/./' and '/../' components.  These converted names are used
for display purposes in the "Switch Session" chooser and in other
places.  If you wish to have the names NOT converted to the "real path"
format, set this YES/NO environment variable to YES, as in

   setenv AFNI_NOREALPATH YES

(For more information on the "real path" conversion, see the Unix
man page for the realpath() function.)  Note that if you use this
feature, then the effect of AFNI_SESSTRAIL will be limited to what
you type on the command line, since it is the realpath() function
that provides the higher level hierarchies of the session names.

----------------------------
Variable: AFNI_NO_MCW_MALLOC
----------------------------
AFNI uses a set of "wrapper" macros and functions to let itself keep
track of the memory allocated and freed by the C malloc() library.
This is useful for debugging purposes (see the last items on the 'Misc'
menu in the AFNI 'Define Datamode' control panel), but carries a small
overhead (both in memory and speed).  Setting this YES/NO environment
variable to YES provides one way to disable this facility, as in

   setenv AFNI_NO_MCW_MALLOC YES

Another way to permanently disable this capability (so that it isn't
even compiled) is outlined in the file machdep.h.  Also, the interactive
AFNI program takes the command line switch "-nomall", which will turn
off these functions for the given run.

N.B.: Setting this variable in the .afnirc file will have no effect,
      since the decision whether to use the routines in mcw_malloc.c
      is made at the very start of the program, before .afnirc is
      scanned.  Therefore, to use this variable, you must set it
      externally, perhaps in your .cshrc or .profile initialization
      file.

------------------------
Variable: AFNI_FIM_BKTHR
------------------------
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 is 10.0, but
values as large as 50.0 may be useful.  This parameter may be changed
interactively from the FIM->Edit Ideal submenu in a graph viewer.

------------------------
Variable: AFNI_FLOATSCAN (editable)
------------------------
If this YES/NO variable is set to YES, then floating point bricks
are checked for illegal values (NaN and Infinity) when they are
read into an AFNI program -- illegal values will be replaced by
zeros.  If a dataset brick contains such illegal values that go
undetected, AFNI programs will probably fail miserably, and have
been known to go into nearly-infinite loops.

Setting this variable implies setting AFNI_NOMMAP to YES, since
only in-memory bricks can be altered (mmap-ed bricks are readonly).

The command line program 'float_scan' can be used to check and
patch floating point files.

[14 Sep 1999] The program to3d will scan input float and complex
files for illegal values, and patch illegal input numbers with
zeros in the output dataset.  If this behavior is not desired for
some bizarre reason, the '-nofloatscan' command line option to
to3d must be used.

-----------------------
Variable: AFNI_NOSPLASH
-----------------------
If this YES/NO variable is set to YES, then the AFNI splash screen
will not be displayed when the program starts.  I'm not sure WHY
you would want to disable this thing of beauty (which is a joy
forever), but if your soul is thusly degraded, so be it.

------------------------
Variable: AFNI_SPLASH_XY
------------------------
If set, this variable should be in the form "100:37" (two integers
separated by a colon).  These values specify the (x,y) screen location
where the splash window's upper left corner will be placed.  If not
set, x will be set to center the splash window on the display and
y will be 100.

-------------------------
Variable: AFNI_SPLASHTIME
-------------------------
The value of this variable determines how long the AFNI splash screen
will stay popped up, in seconds (default value = 5.0).  The splash
screen will always stay up until the first AFNI controller window is
ready for use.  If the time from program start to this ready condition
is less than AFNI_SPLASHTIME, the splash screen will stay up until
AFNI_SPLASHTIME has elapsed; otherwise, the splash screen will be
removed as soon as AFNI is ready to go.  By setting AFNI_SPLASHTIME
to 0.0, you can have the splash screen removed as soon as possible
(and the fade-out feature will be disabled).

-----------------------------
Variable: AFNI_SPLASH_ANIMATE
-----------------------------
If this variable is NO, then the splash screen animation will be disabled.
Otherwise, it will run.

--------------------------------
Variable: AFNI_FIM_PERCENT_LIMIT (editable)
--------------------------------
This sets an upper limit on the % Change that the FIM+ computation
will compute.  For example

  setenv AFNI_FIM_PERCENT_LIMIT 50

means that computed values over 50% will be set to 50%, and values
below -50% will be set to -50%.  This can be useful to avoid scaling
problems that arise when some spurious voxels with tiny baselines have
huge percent changes.  This limit applies to all 3 possible percentages
that FIM and FIM+ can compute: % from baseline, % from average, and
% from top.

---------------------------
Variable: AFNI_NOTES_DLINES
---------------------------
This sets the upper limit on the number of lines displayed in the
Notes plugin, for each note.  If not present, the limit is 9 lines
shown per note at once.  To see a note longer than this limit, you'll
have to use the vertical scrollbar.

-----------------------
Variable: AFNI_FIM_MASK
-----------------------
This chooses the default subset of values computed with the FIM+
button in a graph window.  The mask should be the sum of the desired
values from this list:

    1 = Fit Coef
    2 = Best Index
    4 = % Change
    8 = Baseline
   16 = Correlation
   32 = % From Ave
   64 = Average
  128 = % From Top
  256 = Topline
  512 = Sigma Resid

If you don't set this variable, the default mask is 23 = 1+2+4+16.

-----------------------------------
Variable: AFNI_NO_BYTEORDER_WARNING
-----------------------------------
If this YES/NO variable is set to YES, then AFNI program will not
warn you when reading in a dataset that does not contain a byte
order flag.  The default is to issue such a warning.  Only older
versions of AFNI create datasets that don't have the byte order
flag.  (See also the variable AFNI_BYTEORDER, described far above.)
The purpose of this warning is to alert you to possible problems
when you move datasets between computers with different CPU types.

--------------------------
Variable: AFNI_PCOR_DENEPS
--------------------------
The correlation coefficient calculated in FIM is calculated as the
ratio of two quantities.  If the denominator is negative or zero,
then this value is meaningless and may even cause the program to
crash.  Mathematically, the denominator cannot be zero or negative,
but this could arise due to finite precision arithmetic on the computer
(i.e., roundoff error accumulation).  To avoid this problem, the routine
that computes the correlation coefficient compares the denominator to a
value (called DENEPS) - if the denominator is less than DENEPS, then
the correlation coefficient for that voxel is set to zero.

The denominator that is being computed is proportional to the variance
of the time series.  If the voxel time series data is very small, then
the variance will be really small - so much so that the DENEPS test
will be failed, even though it shouldn't be.  This problem has arisen
when people input time series whose typical value is 0.001 or smaller.
It never occurred to me that people would input data this small to the
AFNI FIM routines.  To get around this difficulty, set this environment
variable to a value for DENEPS; for example
  setenv AFNI_PCOR_DENEPS 0.0
will turn off the checking entirely.  Or you could do
  setenv AFNI_PCOR_DENEPS 1.e-10

-----------------------------
Variable: AFNI_ENFORCE_ASPECT (editable)
-----------------------------
Some Linux window managers do no enforce the aspect ratio (width to height
proportion) request that the image display module makes.  This means that
image windows can become undesirably distorted when manually resized.
Setting this YES/NO variable to YES will make AFNI itself enforce the
aspect ratio whenever an image window is resized.

----------------------------------------
Variables: AFNI_<plug_filename>_butcolor
----------------------------------------
These variables (one for each AFNI plugin) let you set the menu button colors
for the Plugins menu item.  For example
  setenv AFNI_plug_power_butcolor red3
will make the "Power Spectrum" button appear in a dark red color.  The format
of the variable is exemplified above: the <plug_filename> is replaced by the
filename of the plugin (after removing the suffix).  Note that it is possible
for the plugin author to hardcode the menu button for his/her plugin, in
which case the corresponding environment variable will have no effect.

Colors are specified as described in file README.setup.  If you are using
an X11 PseudoColor visual, then you should be economical with color usage!

The purpose of this feature is to let you highlight the plugins that you
use most frequently.  The size of the of plugin menu is growing, and it
is easy to misplace what you most use in the list.

-----------------------------
Variable: AFNI_MARKERS_NOQUAL (editable)
-----------------------------
If this YES/NO variable is set to YES, then the interactive AFNI program
behaves as if the "-noqual" command line option had been included.  This
feature was added at the request of Dr. Michael S. Beauchamp, who has a
very rare neurological disorder called "noqaulagnosia".

----------------------
Variable: AFNI_OPTIONS
----------------------
In the spirit of the previous variable, this variable can be used to set
up command line options that will always be passed to the interactive
AFNI program.  If more than one option is needed, then they should be
separated by spaces, and the whole value of the variable will need to be
placed in quotes.  For example

   setenv AFNI_OPTIONS "-noqual -ncolors 60"

Note that the AFNI command line option "-nomall" cannot be specified this
way (cf. the discussion under variable AFNI_NO_MCW_MALLOC).

------------------------------
Variable: AFNI_NO_SIDES_LABELS (editable)
------------------------------
As of 01 Dec 1999, the interactive AFNI program now displays a label
beneath each image window showing which side of the image is on the left
edge of the window.  This label is based on the anatomical directions
encoded in the anatomical dataset .HEAD file, usually when to3d was used
to create the file.  If you do NOT want these labels displayed (why not?),
set this YES/NO environment variable to YES.

----------------------------------
Variable: AFNI_NO_ADOPTION_WARNING
----------------------------------
AFNI now can print a warning when it forces a dataset to have an anatomy
parent dataset (the "forced adoption" function).  This happens when
there a dataset does not have an anatomy parent encoded into its .HEAD
file (either via to3d or 3drefit), and there is more than one anatomical
dataset in the directory that has Talairach transformation markers
attached.  If you wish to enable this warning, set this YES/NO variable
to NO.  For more information on this subject, please see
  http://afni.nimh.nih.gov/afni/afni_faq.shtml#AnatParent .

-----------------------------------
Variable: AFNI_NO_NEGATIVES_WARNING
-----------------------------------
If this YES/NO variable is set to YES, then to3d will skip the usual
warning that it pops up in a message window when it discovers negative
values in the input short images.  (The warning will still be printed
to stdout.)

-----------------------------------
Variable: AFNI_NO_OBLIQUE_WARNING
-----------------------------------
If this YES/NO variable is set to YES, then the AFNI GUI will skip the usual
warning that it pops up in a message window when an oblique dataset is selected.
(The warning will still be printed to stdout.)

----------------------
Variable: AFNI_NO_XDBE
----------------------
If this YES/NO variable is set to YES, then the X11 Double Buffer
Extension (XDBE) will not be used, even if the X11 server supports it.
This is needed when the X11 server says that it supports it, but actually
does not implement it correctly - this is a problem on the Xsgi server
running under IRIX 6.5.3 on R4400 machines.

------------------------------
Variable: AFNI_VIEW_ANAT_BRICK (editable)
          AFNI_VIEW_FUNC_BRICK (editable)
------------------------------
One of the (very few) confusing parts of AFNI is the "warp-on-demand"
viewing of transformed datasets (e.g., in the +tlrc coordinate system).
This allows you to look at slices taken from transformed volumes without
actually computing and storing the entire transformed dataset.  This
viewing mode is controlled by from the "Define Datamode" control panel.
When an anatomical dataset has a +tlrc.BRIK file, then you can choose
between "View Anat Data Brick" and "Warp Anat on Demand"; when there
is no +tlrc.BRIK file for the dataset, then only "Warp Anat on Demand"
is possible.

If you switch the Talairach view when the current anat dataset does
not have a +tlrc.BRIK file, then the "Warp Anat on Demand" mode will
be turned on.  If you then switch to a dataset that does have a
+tlrc.BRIK file, "Warp Anat on Demand" will still be turned on,
although the "View Anat Data Brick" option will be enabled.

If you set the YES/NO variable AFNI_VIEW_ANAT_BRICK to YES,
then "View Anat Data Brick" will be turned on whenever possible after
switching datasets.  Similarly, setting AFNI_VIEW_FUNC_BRICK to YES
will engage "View Func Data Brick" whenever possible (when the BRIK
file exists and its grid spacing matches the anatomical grid spacing).
Note that switching any dataset (func or anat) triggers the same
routine, and will set either or both "View Brick" modes on.  When
these environment variables are present, the only way to switch to
"Warp" mode when "View Brick" mode is possible is to do it manually
(by clicking on the toggle button) when you want this.

When you use one of the drawing plugins ("Draw Dataset" or "Gyrus Finder"),
you must operate directly on the dataset BRIK.  For this reason, it is
important to be in "View Data Brick" mode on these occasions.  Setting
these variables is one way to ensure that this will happen whenever
possible.

When AFNI is in "Warp Anat on Demand" mode, the word "{warp}" will
appear in the windows' titlebars.  This provides a reminder of the
viewing mode you are using (warped from a brick, or data directly
extracted from a brick), since the "Define Datamode" control panel
will not always be open.

08 Aug 2003: I have modified the way these variables are treated in
AFNI so that they now default to the "YES" behavior.  If you don't
want this, you have to explicitly set them to "NO" from this day forth.

----------------
Variable: TMPDIR
----------------
This variable specifies the directory where temporary files are to be
written.  It is not unique to AFNI, but is used by many Unix programs.
You must have permission to write into this directory.  If you want to
use the current directory, setting TMPDIR to "." would work.  If TMPDIR
is not defined, directory /tmp will be used.  On some systems, this
directory may not have enough space for the creation of large temporary
datasets.  On most Unix systems, you can tell the size of various disk
partitions using a command like "df -k" (on HPUX, "bdf" works).

----------------------------
Variable: AFNI_GRAYSCALE_BOT
----------------------------
This variable sets the darkest level shown in a grayscale image window.
The default value is 55 (a leftover from Andrzej Jesmanowicz).  You can
set this value to anything from 0 to 254.

----------------------------
Variable: AFNI_SYSTEM_AFNIRC
----------------------------
If this variable is set, it is the name of a file to be read like the
user's .afnirc file (see README.setup).  The purpose is to allow a
system-wide setup file to be used.  To do this, you would create such
a file in a useful place - perhaps where you store the AFNI binaries.
Then each user account should have the equivalent of

   setenv AFNI_SYSTEM_AFNIRC /place/where/setup/is/stored/.afnirc

defined in its .cshrc (.bashrc, etc.) file.  Note that it doesn't make
sense to define this variable in the user's .afnirc file, since that
file won't be read until AFTER this file is read.  Also note that use
of the -skip_afnirc option will cause both the system and user setup
files to be skipped.

------------------------
Variable: AFNI_PBAR_IMXY (editable)
------------------------
This variable determines the size of the image saved when the
"Save to PPM" button is selected for a color pbar.  It should be
in the format
  setenv AFNI_PBAR_IMXY 20x256
which means to set the x-size (horizontal) to 20 pixels and the
y-size (vertical) to 256 pixels.  These values are the default,
by the way.

--------------------------
Variable: AFNI_LAYOUT_FILE
--------------------------
If defined, this variable is the name of a file to read at startup
to define the "layout" of AFNI windows at the program start.  If
this name starts with a '/' character, then it is an absolute path;
otherwise, it is taken to be a path relative to the user's home
directory ($HOME).  If the AFNI command line switch "-layout" is
used, it will override this specification.

The simplest way to produce a layout file is to use the "Save Layout"
button on the Datamode->Misc menu.  You can then edit this file;
the format should be fairly self-explanatory.  The structure of the
file is similar to the .afnirc file (cf.  README.setup).  In fact,
the layout file can be included into .afnirc (since it is just another
*** section) and then setting AFNI_LAYOUT_FILE = .afnirc in the
***ENVIRONMENT section should work.

A sample layout file:

***LAYOUT
 A               geom=+73+1106                 // start controller A
 A.sagittalimage geom=320x320+59+159 ifrac=0.8 // and Sagittal image
 A.sagittalgraph geom=570x440+490+147 matrix=9 // and Sagittal graph
 B                                             // start controller B
 B.plugin.ROI_Average                          // start a plugin

Each window to be opened has a separate command line in this file.
The "geom=" qualifiers specify the size and position of the windows.
For images, "ifrac=" can be used to specify the fraction of the window
occupied by the image (if "ifrac=1.0", then no control widgets will be
visible).  For graphs, "matrix=" can be used to control the initial
number of sub-graphs displayed.  For plugins, the label on the button
that starts the plugin is used after the ".plugin." string (blanks
should be filled with underscores "_").  In the example above, the last
two windows to be opened do not have a "geom=" qualifier, so their
placement will be chosen by the window manager.

If you add "slow" after the "***LAYOUT", then each window operation
will be paused for 1 second to let you watch the layout operations
proceed gradually.  Otherwise, they will be executed as fast as
possible (which still may not be all that fast).

Using layouts with a window manager that requires user placement
of new windows (e.g., twm) is a futile and frustrating exercise.

-------------------------
Variable: AFNI_tsplotgeom
-------------------------
Related to the above, if you set this environment variable (in the
***ENVIRONMENT section, not in the ***LAYOUT section), it is used
to set the geometry of the plotting windows used for time series
plots, histograms, etc. -- all the graphs except the dataset plots.
Its format should be something like "550x350"; this example sets
the width to 550 pixels and the height to 350 pixels.  If you don't
set this, the default is "200x200", which is quite small on a high
resolution display.

--------------------------
Variables: AFNI_REALTIME_*
--------------------------
This set of variables allows you to control the initial setup of the
realtime data acquisition plugin (menu item "RT Options").  Normally,
this plugin is active only if AFNI is started with the "-rt" command
line option.  (It will consume CPU time continually as it polls for
an incoming data connection, which is why you don't want it running
by default.)  The following variables can be used to initialize the
plugin's options:

AFNI_REALTIME_Activate = This is a YES/NO variable, and allows you
                         to have the realtime plugin active without
                         using the "-rt" command line option.  If
                         this variable is set to YES, then you can
                         disable the realtime plugin with "-nort".

The variables below are used to set the initial status of the widgets
in the realtime plugin's control window.  Each one has the same name as
the labels in the control window, with blanks replaced by underscores.
The values to set for these variables are exact copies of the inputs
you would specify interactively (again, with blanks replaced by
underscores).  For details as to the meaning of these options, see
the plugin's Help window.

AFNI_REALTIME_Images_Only  = "No" or "Yes"
AFNI_REALTIME_Root         = name for datasets to be created
AFNI_REALTIME_Update       = an integer from 0 to 19
AFNI_REALTIME_Function     = "None" or "FIM" (cf. AFNI_FIM_IDEAL below)
AFNI_REALTIME_Verbose      = "No", "Yes", or "Very"
AFNI_REALTIME_Registration = "None", "2D:_realtime", "2D:_at_end",
                             "3D:_realtime", "3D:_at_end",
                             or "3D:_estimate"
AFNI_REALTIME_Base_Image   = an integer from 0 to 59
AFNI_REALTIME_Resampling   = "Cubic", "Quintic", "Heptic", "Fourier",
                             or "Hept+Four"
AFNI_REALTIME_Graph        = "No", "Yes", or "Realtime"
AFNI_REALTIME_NR           = an integer from 5 to 9999
AFNI_REALTIME_YR           = a floating point number from 0.1 to 10.0

The following internal controls can only be set using these environment
variables (there is no GUI to set these values):

AFNI_REALTIME_volreg_maxite      = an integer >= 1 [default = 9]
AFNI_REALTIME_volreg_maxite_est  = an integer >= 1 [default = 1]
AFNI_REALTIME_volreg_graphgeom   = something like 320x320+59+159

AFNI_REALTIME_CHILDWAIT = max wait time (in sec) for child info
                          process [default = 66.6]; not needed if
                          child info process is not used

AFNI_REALTIME_WRITEWAIT = if the image data pauses for this number
                          of seconds, then the datasets being constructed
                          will be written to disk [default=37.954];
                          since this output may take several seconds,
                          you may need to adjust this if you are in
                          fact doing imaging with a very long TR.
                          Note that after this wait, the plugin can
                          still receive image data -- even if the image
                          source program is silent for a very long time,
                          AFNI will still be waiting patiently for data.

AFNI_GRAPH_AUTOGRID     = By default, if the number of time points in an
                          AFNI graph viewer changes, the density of
                          vertical grid lines changes.  If you don't
                          want this to happen, set this variable to NO.

AFNI_REALTIME_MP_HOST_PORT = HOST:PORT

        When this variable is set, the realtime plugin will attempt to open a
        tcp socket to the corresponding host and port, and will send the six
        registration correction parameters for each 3D volume received by the
        plugin.  This applies only to the case of graphing 3D registration.
        The socket will be opened at the start of each run, and will be closed
        at the end.  A simple example of what to set this variable to is
        localhost:53214.
        See 'serial_helper -help' for more details.

AFNI_REALTIME_SEND_VER   = Y/N

        If AFNI_REALTIME_MP_HOST_PORT is set, the RT plugin has 3 choices
        of what to send to that port (possibly to serial_helper):
            0. the motion parameters
            1. motion params, along with average EPI values over each ROI
               in the mask dataset (if set)
            2. motion params, along with all voxel values over the mask
               dataset (including index, i,j,k and x,y,z values)
        If AFNI_REALTIME_SEND_VER is set to YES, then the plugin will offset
        the last byte of the communication HELLO string by the version number
        (0, 1 or 2).  In the case of versions 1 or 2, the plugin will send
        the number of ROIs/voxels in a 4-byte int after the HELLO string.

AFNI_REALTIME_Mask_Vals  = String (one of the listed strings)

        This allows the user to set the "Vals to Send" field from the RT
        plugin's "Mask" line.  It determines what data are sent to the remote
        MP program (e.g. serial_helper).  Valid strings are:

            None        - send nothing
            Motion_Only - send only the 6 registration parameters
            ROI_means   - send the mean EPI value per mask ROI (value) per TR
            All_Data    - send each voxel value (in mask) per TR

AFNI_REALTIME_SHOW_TIMES = Y/N

        If set, the RT plugin will output CPU times whenever motion parameters
        are sent to the remote program, allowing evaluation of timing.  The
        times are modulo one hour, and are at a millisecond resolution.

For more information about how the realtime plugin works, read the file
README.realtime.

Also see "Dimon -help" (example E "for testing complete real-time system").
Also see "serial_helper -help".

------------------------
Variable: AFNI_FIM_IDEAL
------------------------
This variable specifies the filename of the initial FIM ideal timeseries.
The main use of this would be to be able to initialize the Realtime
plugin without direct user intervention.

--------------------------
Variable: AFNI_FIM_SAVEREF
--------------------------
When you run the interactive AFNI 'fim' (from the graph viewer FIM menu),
the program saves the reference time series (and ort time series, if any)
in the new functional dataset header, with the attribute name
AFNI_FIM_REF (or AFNI_FIM_ORT).  If you do NOT want this information saved,
then set this variable to NO.  Two sample ways to use this information is
the command below:
  1dplot "`3dAttribute -ssep ' ' AFNI_FIM_REF r1_time@1+orig`"
  1dcat  "`3dAttribute -ssep ' ' AFNI_FIM_REF r1_time@1+orig`" > ref.1D
The 3 different styles of Unix quotes must be used exactly as shown here!

----------------------------------
Variable: AFNI_PLUGINS_ALPHABETIZE
----------------------------------
If this YES/NO variable is set to NO, then the plugin buttons will
not be alphabetized on the menu,  and they will appear in the
order which AFNI chooses.  Otherwise, the plugin menu buttons will
be alphabetized by default. Alphabetizing is done without regard to
case (using the C library routine strcasecmp).

----------------------------
Variable: AFNI_VOLREG_EDGING
----------------------------
This variable affects the operation of 3dvolreg, the volume registration
plugin, and the 3D registration code in the realtime acquisition plugin.
It determines the size of the region around the edges of the base volume
where the default weight will be set to zero.  Call the value of this
variable 'ee'.  If 'ee' is a plain number (e.g., 5), then it is a voxel
count, giving the thickness along each face of the 3D brick.  If 'ee' is
of the form '5%', then it is a fraction of of each brick size.  For
example, '5%' of a 256x256x124 volume means that 13 voxels on each side
of the xy-axes will get zero weight, and 6 along the z-axis.  '5%' is
the default value used by the 3D registration routines (in mri_3dalign.c)
if no other value is specified.

--------------------
Variable: AFNI_TRACE
--------------------
This variable controls the initial setting of the tracing (debugging)
code when AFNI programs startup.  If it is set to 'y', then tracing
is turned on and set to the LOW mode (like -trace in AFNI).  If it is
set to 'Y', then tracing is turned on and set to the HIGH mode (like
-TRACE in AFNI).  Anything else, and tracing is turned off.

N.B.: You can't set this variable in .afnirc and expect it to have
      any effect (and why would you want to?), since it is read from
      the environment BEFORE the .afnirc file is read in.

N.B.: At this moment (26 Jan 2001), only the AFNI program itself is
      configured for tracing.  As time goes on, the entire AFNI
      programming library and suite of programs will be revamped for
      this purpose.  The goal is to make it easier to find bugs, and
      localize crashes.

-------------------------
Variable: AFNI_TRACE_FILE
-------------------------
If this variable is set, then the output from the AFNI function tracing
macros will be written to a file with that name, rather than to stdout.
This variable cannot be set in .afnirc; the intention is to provide a
way to get 'clean' tracing output (not mixed up with other program junk)
that can be fed to Ziad Saad's AnalyzeTrace function.

------------------------
Variable: AFNI_ROTA_ZPAD
------------------------
This variable controls the amount of zero-padding used during 3D rotations
in 3drotate, 3dvolreg, etc.  It provides a default value for the "-zpad"
options of these programs.  If zero-padding is used, then this many voxels
are padded out on each edge (all 6 faces) of a 3D brick before rotation.
After the rotation, these perimeter values (whatever they might be) will
be stripped off.  If "-zpad" is used on the command line, it overrides
this value.  Zero padding during rotation is useful to avoid edge effects,
the worst of which is the loss of data off the edge of the volume during
the 4 shearing stages.

------------------------
Variable: AFNI_TO3D_ZPAD
------------------------
This variable sets the number of slices added on each z-face in datasets
created by program to3d.  It provides a default value for the "-zpad" option
of that program.  It can be set to an integer, meaning a slice count, or
a number of millimeters, meaning a minimum distance to pad:
   setenv AFNI_TO3D_ZPAD 2
   setenv AFNI_TO3D_ZPAD 16mm
If "-zpad" is used on the to3d command line, it overrides this value.
If neither is present, no zero padding is used.  Note well that this
padding is only in the z-direction, unlike that of AFNI_ROTA_ZPAD.

----------------------------
Variable: AFNI_IMAGE_MINFRAC (editable)
----------------------------
This variable sets the minimum size of an image window when it is first
opened, in terms of a fraction of the overall screen area.  By default,
this value is set to 0.02; you can override this by (for example)
   setenv AFNI_IMAGE_MINFRAC 0.05
If you set this value to 0.0, then there will be no minimum.  This is
the old behavior, where the initial window size is always 1 screen pixel
per data pixel, and can lead to image windows that are hard to resize or
otherwise use (when the dataset is small).  The largest value I recommend
for AFNI_IMAGE_MINFRAC is 0.1; however, you can set it to as large as 0.9
if you are completely crazy, but I'm not responsible for the results --
don't even think of complaining or commenting to me about problems that
arise if you try this!

----------------------------
Variable: AFNI_IMAGE_MAXFRAC
----------------------------
This variable sets the maximum size of an image window, as a fraction of
the width and height of the screen.  The default value is 0.9.  This lets
you prevent image windows from auto-resizing to be too big when you
change datasets.  Note that if you have turned on AFNI_ENFORCE_ASPECT, then
this feature will prevent you from resizing a window to be larger than
the AFNI_IMAGE_MAXFRAC fraction of the screen dimensions.

-----------------------
Variable: AFNI_AUTOGZIP (cf. AFNI_COMPRESSOR) (editable)
-----------------------
If this YES/NO variable is set to YES, then when AFNI programs write a
dataset .BRIK file to disk, they will test to see if the data is easily
compressible (at least 80%).  If so, then the GZIP compression will be
used.  (For this to work, the gzip program must be in your path.) This
can be useful if you are dealing with mask datasets, which are usually
highly compressible, but don't want the overhead of trying to compress
and decompress arbitrary MRI datasets.

A command line method to carry out compression of datasets that will
compress well is to use a csh script like the following:

  #!/bin/csh
  foreach fred ( `find . -name \*.BRIK -print` )
    ent16 -%50 < $fred
    if( $status == 1 ) gzip -1v $fred
  end

This will only gzip .BRIK files that the program ent16 estimates will
compress by at least 50%.  Note that ent16's estimate of compression
may be high or low relative to what gzip actually does.

------------------------------
Variable: AFNI_DONT_MOVE_MENUS (editable)
------------------------------
If this YES/NO variable is set to YES, then the functions that try
to move popup menus to "good" locations on screens will be skipped.
This seems to be necessary on some Solaris systems, where the menus
can end up being moved to bizarre locations.

----------------------------
Variable: AFNI_MINC_DATASETS
----------------------------
If this YES/NO variable is not set to NO, then MINC-format files
with name suffix .mnc will be read into the interactive AFNI
program at startup, along with standard .HEAD/.BRIK datasets.
That is, you have to set this variable explicitly to NO if you
don't want MINC-format files to be automatically recognized by
the interactive AFNI program.  This variable does not affect
the ability of command line programs (3dSomething) to read
.mnc input files.

----------------------------
Variable: AFNI_MINC_FLOATIZE
----------------------------
If this YES/NO variable is set to YES, then when MINC-format files
are read in as datasets, their values will be scaled to floats.
Otherwise, their values will be scaled to the same data type as
stored in the file.  In some cases, the latter behavior is not
good; for example, if a byte-valued file (intrinsic range 0..255)
is scaled to the range 0..0.5 in the MINC header, then after
conversion back to bytes, the resulting AFNI dataset values will
all be zero.  Setting AFNI_MINC_FLOATIZE to YES will cause the
scaled values to be stored as floats.

------------------------------
Variable: AFNI_MINC_SLICESCALE
------------------------------
If this YES/NO variable is set to NO, then AFNI will not use the
image-min and image-max scaling when reading data from MINC files.
Normally, you want this scaling, since MINC files are scaled separately
in each slice.  However, if the image-min and image-max values in the
MINC file are damaged, then you can turn off the scaling this way.

----------------------------
Variable: AFNI_ANALYZE_SCALE
----------------------------
If this YES/NO variable is set to NO, then the "funused1" entry
in the Mayo Analyze .hdr file will not be used as a scale factor
for the images contained in the corresponding .img file.  Otherwise,
if funused1 is positive and not equal to 1.0, all the image data
in the .img file will be scaled by this value.

-------------------------------
Variable: AFNI_ANALYZE_FLOATIZE
-------------------------------
If this YES/NO variable is set to YES, then Mayo Analyze files
will be scaled to floats on input.  Otherwise, they will be read
in the format in which they are stored in the .img file.  Conversion
to floats can be useful if the scaling factor is such that the image
native format can't hold the scaled values; for example, if short
values in the image range from -1000..1000 and the scale factor
is 0.0001, then the scaled values range from -0.1..0.1, which would
be truncated to 0 in the scaled image if it is not "floatized".
(Conversion to floats will only be done to byte, short, and int
image types.)

---------------------------------
Variable: AFNI_ANALYZE_ORIGINATOR
---------------------------------
If this YES/NO variable is set to YES, then AFNI will attempt
to read and use the ORIGINATOR field in a Mayo Analyze file
to set the origin of the pixel space in AFNI.  This origin
can be used directly by several programs--the main AFNI viewer,
and all of the 3dxxxx programs, including especially 3dcopy,
which is the preferred way to convert an Analyze format file
to an AFNI native file.
This variable will also force 3dAFNItoANALYZE to write the
ORIGINATOR field into the output Analyze file based on the
input AFNI file's origin information.
The ORIGINATOR field should be compatible with SPM in most
cases, but please verify this.

--------------------------
Variable: AFNI_START_SMALL
--------------------------
If this YES/NO variable is set to YES, then when AFNI starts, it will
look for the smallest datasets in the first session, and choose these
as its starting point.  This can be useful if you also use the layout
feature to pop open an image window on startup; in that case, if the
default starting dataset (the first alphabetical) is huge, you won't
see anything while the program reads all of into memory before displaying
the first image.

---------------------------
Variable: AFNI_MENU_COLSIZE
---------------------------
This numerical variable sets the maximum number of entries in a popup
menu column (e.g., like the sub-brick menus for bucket datasets).  The
default value is 20, but you may want to make this larger (say 40).  When
you have a menu with a huge number of entries, the menu can become so
wide that it doesn't fit on the screen.  Letting the columns be longer
will make the menus be narrower across the screen.

Another way to get a handle on such huge menus is to Button-3 (right)
click on the label to the left of the menu.  This will popup a one-
column scrollable list chooser that is equivalent to the menu.  In this
way, it is still possible to use menus that have hundreds of entries.
The maximum number of entries shown at one time in a scrollable list
chooser is given by variable AFNI_chooser_listmax if it exists, otherwise
by AFNI_MENU_COLSIZE.

-----------------------------
Variable: AFNI_GLOBAL_SESSION
-----------------------------
This variable, if it exists, is the name of a directory that contains
"global" datasets - ones that you want to be visible in each "Switch Underlay"
or "Switch Overlay" menu.  Pointers to the datasets read from this directory
will be appended to the dataset list for each directory read from the
command line.  In the "Switch" choosers, these datasets are marked with
the character 'G' at the right, and they appear last in the list.

It really only makes sense to put +tlrc datasets in the global session
directory, since only they can be presumed to be aligned with other datasets.
Also, it is probably best if you make sure each global anatomical dataset
has itself as the anatomy parent; this can be enforced by issuing the command
  3drefit -apar SELF *.HEAD
in the global session directory.

When you Switch Sessions and are viewing a global dataset, it is likely that
you will NOT be viewing the same dataset after the Switch Session.  You will
have to then Switch Underlay and/or Switch Overlay to get back to the same
global dataset(s).

If you start AFNI and there are no datasets in the sessions given on the
command line, then the directory specified by this variable becomes the
default session.  If there are no datasets there, either, then AFNI makes
up a dummy dataset (AFNI cannot operate without at least one dataset).

------------------------------
Variable: AFNI_DISP_SCROLLBARS (editable)
------------------------------
If this YES/NO variable is set to YES, then the 'Disp' control window
(on the image viewers) will have scrollbars attached.  This window has
grown larger over the years, and for some people with pitifully small
displays (e.g., laptops), it is now taller than their screens.  If
activated, this option will prevent the Disp window from being so tall
and will attach scrollbars so you can access all of its contents.

Note: If you change this value interactively, via Edit Environment, the
change will only affect Disp windows opened after you 'Set' the variable.
That is, already opened Disp windows won't suddenly get scrollbars if
you change this to YES.

------------------------------
Variable: AFNI_GRAPH_TEXTLIMIT (editable)
------------------------------
This numerical variable sets the upper limit on the number of rows shown
in the Button-3 popup in a sub-graph.  If the number of rows in the popup
would be more than this value, a text window with scrollbars is used
instead of a "spring-loaded" menu pane.  If you set this value to 1, then
the text window will always be used.  Note that a text window does not
automatically popdown, but must be explicitly dismissed by the user
pressing the "Quit" button.

-----------------------------
Variable: AFNI_GRAPH_BASELINE
-----------------------------
This variable should be set to one of the strings "Individual", "Common",
or "Global", corresponding to the choices on the Opt->Baseline menu in
a graph window.  (Actually, only the first letter of the string will be
used.)  This variable will determine the initial setting of the Baseline
menu when a graph window opens.

-------------------------------
Variable: AFNI_GRAPH_GLOBALBASE
-------------------------------
Normally, the global baseline for a graph window is set to the smallest
value found in the entire 3D+time dataset.  This variable lets you specify
a numerical value to be used for this purpose instead.  Probably the most
common setting (for those who want to use this feature at all, which means
Mike Beauchamp) would be
  setenv AFNI_GRAPH_GLOBALBASE 0
Of course, you can always change the global baseline from the Opt->Baseline
menu.

--------------------------
Variable: AFNI_VALUE_LABEL (editable)
--------------------------
If this YES/NO variable is set to YES, then the data value label on the
Define Overlay control panel will be turned on when only 1 or 2 image
viewer windows are open.  This will consume more CPU time and redrawing
time than the default, which is that this label is only turned on when
all 3 image viewer windows are open.  If you are operating X11 remotely
over a slow connection, this option should not be turned on.

----------------------------
Variable: AFNI_SUMA_BOXCOLOR (editable)
----------------------------
This string defines the color used for overlaying surface nodes transmitted
from SUMA to AFNI.  The default is an orangish-yellow.  If you like yellow,
then do
   setenv AFNI_SUMA_COLOR yellow
If this is set to "none", then these lines won't be plotted.

-----------------------------
Variable: AFNI_SUMA_LINECOLOR (editable)
-----------------------------
This string defines the color used for overlaying the intersection of SUMA
surface triangles with image slice planes.  The default is white.  If this
is set to "none", then these lines won't be plotted.

---------------------------
Variable: AFNI_SUMA_BOXSIZE (editable)
---------------------------
This variable defines the size of the boxes drawn at each surface node
transmitted from SUMA.  The default is 0.25, which means that each box is
plus and minus 1/4 of a voxel size about the node location. If you want a
larger box, you could try
   setenv AFNI_SUMA_BOXSIZE 0.5

----------------------------
Variable: AFNI_SUMA_LINESIZE (editable)
----------------------------
This variable sets the thickness of the lines used when drawing a surface
intersection overlay.  The units are the width of the entire image;
reasonable values are in the range 0..0.01; 0 means to draw the thinnest
line possible.  Since this is editable, you can experiment with it to
see what looks good.

-------------------------
Variable: AFNI_NIML_START
-------------------------
If this YES/NO variable is set to YES, then NIML listening will be engaged
from when AFNI starts.  You can also enable NIML from the command line with
the option "-niml", and from the Datamode->Misc menu item "Start NIML".

NIML is the mechanism by which AFNI talks to other programs - it is the
successor to plugouts.  At this moment (Mar 2002), the only external NIML
program is SUMA - the surface mapper.

---------------------------
Variable: AFNI_KEEP_PANNING (editable)
---------------------------
If this YES/NO variable is set to YES, then when the Zoom pan gets turned
on in the AFNI image viewer, it will stay on until it is explicitly turned
off.  (The default behavior is to turn panning off after the user releases
the mouse button.)

-------------------------------
Variable: AFNI_IMAGE_LABEL_MODE
-------------------------------
This integer determines the placement of the image coordinate labels drawn
in the AFNI image viewer windows.  The possible values are
   0  =  Labels are off
   1  =  Labels in upper left
   2  =  Labels in upper right
   3  =  Labels in lower left
   4  =  Labels in lower right
   5  =  Labels in upper middle
   6  =  Labels in lower middle
You can also control the placement and size of the labels from the Button-3
(right-click) popup menu attached to the intensity bar to the right of the
image sub-window.

-------------------------------
Variable: AFNI_IMAGE_LABEL_SIZE
-------------------------------
This integer determines the size of the image coordinate labels:
   0  =  Small
   1  =  Medium
   2  =  Large
   3  =  Huge
   4  =  Enormous

--------------------------------
Variable: AFNI_IMAGE_LABEL_COLOR (editable)
--------------------------------
This variable controls the color of the image coordinate labels.

----------------------------------
Variable: AFNI_IMAGE_LABEL_SETBACK (editable)
----------------------------------
This variable, a floating point value between 0 and 0.1, determines how
far from the edge an image coordinate label will be drawn.  The units are
fractions of the image width/height.

------------------------------
Variable: AFNI_CROSSHAIR_LINES (editable)
------------------------------
If this YES/NO variable is set to YES, then the image crosshairs will be
drawn using lines rather than pixels.  By default (this is the original
AFNI way), crosshair lines are drawn the same way as functional overlays:
by putting color pixels on top of the image.  The new way draws lines on
top of the image instead.  The difference is quite visible when the image
is zoomed; overlay by pixels shows the crosshair lines as fat blobs, but
the lines are drawn as thin as possible, no matter what the image window
size and zoom factor.

Good points about crosshairs drawn with lines:
 - They are less obtrusive than pixel overlay, especially if you zoom
     or enlarge the image a lot
 - When doing a montage with Spacing=1, they'll look better in the
     orthogonal slices.
Good points about crosshairs drawn with pixel overlay:
 - Pixel overlays can be rendered as translucent (on X11 TrueColor displays);
     geometrical overlays are always solid color.
So you have to decide what you need most.  You can change this item using
the "Edit Environment" pseudo-plugin on the Datamode->Misc menu, so you
can play with it interactively to get the features you want.

----------------------------
Variable: AFNI_CROP_ZOOMSAVE (editable)
----------------------------
When saving a zoomed image, the default is to save the entire zoomed image,
not just the part you see.  If this YES/NO variable is set to YES, then only
the visible part will be saved.

---------------------------
Variables: AFNI_TLRC_BBOX_*
---------------------------
These variables let you choose the size of the "Talairach Box", into which
+tlrc datasets are transformed.  If defined, they should be positive values,
in mm.  The 5 variables (any or all of which may be used) are:

  AFNI_TLRC_BBOX_LAT = distance from midline to maximum left/right position
                        [default=80]
  AFNI_TLRC_BBOX_ANT = distance from AC to most anterior point in box
                        [default=80]
  AFNI_TLRC_BBOX_POS = distance from AC to most posterior point in box
                        [default=110]
  AFNI_TLRC_BBOX_INF = distance from AC-PC line to most inferior point in box
                        [default=55 for small box, 65 for big box]
  AFNI_TLRC_BBOX_SUP = distance from AC-PC line to most superior point in box
                        [default=85]

For example, "setenv AFNI_TLRC_BBOX_INF 100" lets you define the +tlrc box
to extend 100 mm below the AC-PC line.  Please note that virtually all the
3d* analysis programs (3dANOVA, etc.) do voxel-by-voxel analyses.  This fact
means that you will be unable to compare datasets created in +tlrc coordinates
with different box sizes.  Also, you will be unable to overlay regions from
the Talairach Daemon database onto odd-sized +tlrc datasets.  Therefore, I
recommend that these variables be used only when strictly needed, and with
caution.

Lastly, try hard not to mix TLRC datasets created with various box sizes in
the same session. Strange things may happen.

---------------------------
Variables: AFNI_ACPC_BBOX_*
---------------------------
The variables let you choose the size of the "ACPC Box", into which
+acpc datasets are transformed. If defined, they should be positive values,
in mm.  The 6 variables (any or all of which may be used) are:

  AFNI_ACPC_BBOX_LAT = distance from midline to maximum left/right position
                        [default=95]
  AFNI_ACPC_BBOX_ANT = distance from AC to most anterior point in box
                        [default=95]
  AFNI_ACPC_BBOX_POS = distance from AC to most posterior point in box
                        [default=140]
  AFNI_ACPC_BBOX_INF = distance from AC-PC line to most inferior point in box
                        [default=70]
  AFNI_ACPC_BBOX_SUP = distance from AC-PC line to most superior point in box
                        [default=100]

Check example and heed ALL warnings for variables AFNI_TLRC_BBOX_* above.

-------------------------
Variable: AFNI_TTRR_SETUP
-------------------------
Name of a file to be loaded to define Talairach Atlas Colors, when the Atlas
Colors control panel is first created.  Format is the same as a file created
from this control panel's "Save" button.  This filename should be an absolute
path (e.g., /home/yourname/.afni_ttcolors), since otherwise it will be read
relative to the directory in which you start AFNI.

-----------------------------
Variable: AFNI_LOAD_PRINTSIZE
-----------------------------
AFNI will print (to stderr) a warning that it is loading a large dataset from
disk.  This value determines the meaning of "large".  For example, setting
this variable to "40M" means that loading a dataset larger than 40 Megabytes
will trigger the warning.  If not given, the default value is 100 Megabytes.
The purpose of the warning is just to let the user know that it may be several
seconds before the dataset is loaded (e.g., before the images appear).  If you
don't want this warning at all, set this variable to the string "0".

-------------------------------
Variable: AFNI_ANALYZE_DATASETS
-------------------------------
If this YES/NO variable is not set to NO, then ANALYZE-format files with name
suffix .hdr will be read into the interactive AFNI program at startup, along
with standard .HEAD/.BRIK datasets.  That is, you have to set this variable
explicitly to NO if you don't want ANALYZE-format files to be automatically
recognized by the interactive AFNI program.  This variable does not affect
the ability of command line programs (3dSomething) to read .hdr input files.

-----------------------------
Variable: AFNI_ANALYZE_ORIENT
-----------------------------
ANALYZE .hdr files do not contain reliable information about the orientation
of the data volumes.  By default, AFNI assumes that these datasets are
oriented in LPI order.  You can set this variable to a different default
order.  See AFNI_ORIENT for details on the 3 letter format for this.

---------------------------------
Variable: AFNI_ANALYZE_AUTOCENTER
---------------------------------
ANALYZE .hdr files do not contain information about the origin of coordinates.
The default AFNI approach mirrors that of FSL - the outermost corner of the
first voxel in the dataset is set to (0,0,0).  If you set this variable
(AFNI_ANALYZE_AUTOCENTER) to YES, then instead (0,0,0) will be set to the
center of the 3D ANALYZE array.  This is the default that would be applied
if you read the ANALYZE array into program to3d.

----------------------------
Variable: AFNI_VERSION_CHECK
----------------------------
If this YES/NO variable is set to NO, then AFNI will not try to check if its
version is up-to-date when it starts.  Otherwise, it will try to check the
program version with the AFNI web server.

-------------------------
Variable: AFNI_MOTD_CHECK
-------------------------
Similarly, if this YES/NO variable is set to NO, then AFNI will not display
and fetch the AFNI "Message of the Day" at startup.  You can always check
the MOTD by using the Datamode->Misc menu.

-----------------------------------
Variable: AFNI_SLICE_SPACING_IS_GAP
-----------------------------------
This YES/NO variable is designed to patch a flaw in some DICOM files, where
the "Spacing Between Slices" attribute is erroneously set to the gap between
the slices, rather than the center-to-center slice distance specified in
the DICOM standard.  If this variable is set to YES, then the "Slice Thickness"
attribute will always be added to "Spacing Between Slices" to get the z voxel
size (assuming both attributes are present in the DICOM file).

To check if a DICOM file has this problem, you can read it into to3d with
the command "to3d suspect_file_name".  A warning will be printed to the
terminal window if attribute "Spacing Between Slices" is less than
attribute "Slice Thickness".  Another way to check is with a command like so

  dicom_hdr suspect_file_name | grep "Slice"

then check if the "Spacing Between Slices" and "Slice Thickness" values are
correct for the given acquisition.  We have only seen this problem in GE
generated DICOM files, but that doesn't mean it won't occur elsewhere.

If this variable is set to NO, then this patchup will never be made.
The z voxel size will be set to "Spacing Between Slices" if present,
otherwise to "Slice Thickness".  This may be needed for some Phillips pulse
sequences, which can report "Spacing Between Slices" < "Slice Thickness".
In such a case, if this variable is not set, the wrong z voxel size will
be assigned!

If this variable is not set at all, AND if "Spacing Between Slices" is less
less than 0.99 times "Slice Thickness", it will be treated as a gap;
that is, the z voxel size will again be set to "Spacing Between Slices" +
"Slice Thickness" if "Spacing Between Slices" < 0.99*"Slice Thickness".
Otherwise, the z voxel size will be set to the larger of
"Spacing Between Slices" and "Slice Thickness".

N.B.: "YES", "NO", and "not set" have 3 different sets of behavior!
      In the summary below, if a variable isn't set, treat it as zero:

  YES     => dz = Thickness + Spacing
  NO      => dz = Spacing if present, otherwise Thickness
  not set => if( Spacing > 0 && Spacing < 0.99*Thickness )
               dz = Thickness + Spacing
             else
               dz = MAX( Thickness , Spacing )

If neither variable is set, then dz=1 mm, which is probably wrong.

Sorry about this complexity, but the situation with various manufacturers
is complicated, murky, and confusingly maddening.

---------------------------------------------------
Variables: AFNI_DICOM_RESCALE and AFNI_DICOM_WINDOW
---------------------------------------------------
DICOM image files can contain rescaling and windowing "tags".  If present,
these values indicate to affinely modify the values stored in the file.
As far as I can tell, "rescale" means that the values should always be
modified, whereas "window" means the values should be modified for display
purposes.  If both are present, the rescale comes before window.  These
two YES/NO environment variables control whether the AFNI image input
functions (used in to3d) should apply the rescale and window tags.

It is my impression from the laconic, terse, and opaque DICOM manual that
window tags are intended for display purposes only, and that they aren't
needed for signal processing.  But you'll have to examine your own data to
decide whether to use these options -- manufacturers seem to differ.
Plus, I don't have that much experience with DICOM data from many different
sources.

-----------------------
Variable: IDCODE_PREFIX
-----------------------
AFNI stores with each dataset a unique string, called an "idcode".  An example
is "XYZ_MoNLqdNOwMNEYmKSBytfJg".  You can alter the first three characters of
the idcode with this variable.  For example,
  setenv IDCODE_PREFIX RWC
sets the first 3 characters of newly generated idcodes to be the initials of
AFNI's author.  I find this a handy way to "brand" my datasets.  Of course,
there are only 17576 possible 3 letter combinations (140608 if you allow for
case), so you should claim your prefix soon!!!

Idcodes are used to store links between datasets.  For example, when SUMA
sends a surface to AFNI, it identifies the dataset to which the surface is
to be associated with the dataset's idcode.  Similarly, when AFNI sends a
color overlay to SUMA, it uses the surface idcode to indicate which surface
family the overlay is to be mapped onto.

-------------------------
Variable: AFNI_AGIF_DELAY
-------------------------
This is the time delay between frames when writing an animated GIF file from
an image viewer window.  The units are 100ths of seconds; the default value
is 20 (= 5 frames per second).

-----------------------------
Variable: AFNI_MPEG_FRAMERATE
-----------------------------
This value sets the frame rate (per second) of the MPEG-1 output animation
from the image viewer window.  The legal values allowed by MPEG-1 are
24, 25, 30, 50, and 60; 24 is the default.

-----------------------------
Variable: AFNI_STARTUP_SCRIPT
-----------------------------
If this is set, this is the name of an AFNI Script to run when AFNI first
starts.  (See the file README.driver for information about AFNI Scripts.)
If this is not set, it defaults to ".afni.startup_script".  The program first
tries to read this filename from the current working directory; if that fails,
then it tries to read from your home directory.  No error message is given
if neither file can be read.

You can save a file ".afni.startup_script" that will recreate the window
layout you currently have.  Use the "Datamode->Misc->Save Layout" button
and press "Set" on the popup control without entering any filename.  Instead
of a Layout file (cf. AFNI_LAYOUT_FILE above), you'll get a Script file
if you leave the filename blank or enter any filename with the string
"script" included (e.g., "coolstuff.script").

The capabilities of Script files are being expanded.  Not all features of
the AFNI window setup are currently save-able this way.

You can load a Script file interactively during an AFNI run by using the
button "Datamode->Misc->Run Script".  As a 'secret' option, if you enter
a line containing a blank in the the filename dialog, that line will be
executed as a single command, rather than be used as a script filename.

------------------------------
Variable: AFNI_DEFAULT_OPACITY
------------------------------
This should be set to an integer from 1..9, and controls the default opacity
setting for the color overlay in image viewer windows.

-----------------------------
Variable: AFNI_DEFAULT_IMSAVE
-----------------------------
This should be set to the suffix of the image format to which you want to save
from an image viewer.  The suffixes AFNI knows about (as of 23 Jan 2003) are
 ppm = Portable PixMap format                            = cat
 jpg = Joint Photographics Experts Group (JPEG) format   = cjpeg
 gif = Compuserve Graphics Interchange File (GIF) format = ppmtogif
 tif = Tagged Image File Format (TIFF)                   = ppm2tiff or pnmtotiff
 bmp = Windows Bitmap (BMP) format                       = ppmtobmp
 eps = Encapsulated PostScript format                    = pnmtops
 pdf = Portable Document Format                          = epstopdf
 png = Portable Network Graphics format                  = pnmtopng
The third column is the name of the external filter program that AFNI uses to
write the format.  If a filter is not present on your system, then that option
is not available.  Most of these filters are part of the netpbm package.

-----------------------------
Variables: AFNI_COLORSCALE_xx  for xx=01, 02, ..., 99
-----------------------------
These variables let you name files to be read it at AFNI startup to define
"continuous" colorscales for the "**" mode of the color pbar.  These files
will be looked for in the current directory when you start AFNI, or in your
home directory (if they aren't in the current directory).  A sample file:

  Yellow-Red-Blue
  1.0 #ffff00
  0.7 #ffaa00
  0.5 #ff0000
  0.3 #aa00aa
  0.0 #0000ff

The first line is the name of this colorscale, to go in the colorscale popup
chooser.  The succeeding lines each have a number and a color definition.
The numbers should be decreasing, and indicate the location on the colorscale.
The largest number corresponds to the top of the colorscale and the smallest
to the bottom - intermediate numbers denote intermediate locations.  The colors
at each location are specified using X11 notation (cf. "man XParseColor").
In this example, I'm using hexadecimal colors, in the form #rrggbb, where each
hex pair ranges from 00 to ff.  Another color format is "rgbi:rf/gf/bf",
where each value rf,gf,bf is a number between 0.0 and 1.0 (inclusive); for
example, yellow would be "rgbi:1.0/1.0/0.0".

Colors are interpolated (linearly in RGB space) between the break locations
given in the file.  There are actually 128 color locations on a colorscale.

An alternative format for the file is to omit the numbers indicating the
break locations.  In this case, the break locations will be taken to be
equally spaced.  For example:

  Yellow-Red-Blue
   #ffff00
   #ffaa00
   #ff0000
   #aa00aa
   #0000ff

This example is not exactly the same as the other one, since the breakpoints
are evenly spaced now (as if they had been given as 1.0, 0.75, 0.5, 0.25,
and 0.0).  With this format, if you want to manually specify all 128 colors,
you can do so, 1 color per line, remembering that the first line of the file
is taken to be the colorscale title (no blanks allowed in the title!).

---------------------------------
Variable: AFNI_COLORSCALE_DEFAULT
---------------------------------
If set, this is the name of the default colorscale to use in setup.  As a
special case, if you DO NOT want a colorscale to be setup by default at all,
then set this variable to the string "NO".
N.B.: This variable only applies if you are using AFNI with a TrueColor X11
visual.  If you are using a PseudoColor visual, then this variable is ignored!

----------------------------
Variable: AFNI_RESCAN_METHOD
----------------------------
On 28 Dec 2002, I modified the way that the "Rescan" operation in AFNI works
when re-reading datasets from sessions.  The old way would purge and replace
all datasets; the new way just adds datasets that didn't exist before.
There are some differences between these methods:
  "Replace" will detect changes to a dataset, so if you add a brick using
    3dTcat -glueto (for example), this will be reflected in AFNI.
  "Replace" will cause troubles if you are using a dataset in a plugin;
    the two main examples are volume rendering and the drawing plugin.
    This problem will occur even if you didn't do anything to the dataset
    on disk, since the internal pointer to the dataset will have been
    changed by the rescan, but the plugins won't know that.
  "Add" will not detect changes to a dataset on disk, but it also won't
    affect the pointers to the existing datasets.
You can choose to use the "Replace" method (the old style) by setting
this environment variable to the string "REPLACE".

---------------------------
Variable: AFNI_OLD_PPMTOBMP
---------------------------
The old (before 21 Feb 2003) usage of netpbm program "ppmtobmp" was to
write a color image quantized to 255 colors.  The new usage is to write
a 24-bit image, which is thus not color-quantized.  If you want the old
behavior, set this environment variable to YES.  This setting (YES) will
be necessary if you have an older version of ppmtobmp in your path, which
doesn't support the "-bpp" option.

------------------------------
Variable: AFNI_1DPLOT_COLOR_xx
------------------------------
This variable lets you set the colors used in the 1dplot program (and other
similar graphs).  Here, "xx" is a number from "01" to "19".  The value of
the environment variable must be in the form "rgbi:rf/gf/bf", where each
color intensity (rf, gf, bf) is a number between 0.0 and 1.0.  For example,
"rgbi:1.0/1.0/0.0" is yellow.  By default, the first 4 colors are defined
as the equivalents of
  setenv AFNI_1DPLOT_COLOR_01 rgbi:0.0/0.0/0.0
  setenv AFNI_1DPLOT_COLOR_02 rgbi:0.9/0.0/0.0
  setenv AFNI_1DPLOT_COLOR_03 rgbi:0.0/0.7/0.0
  setenv AFNI_1DPLOT_COLOR_04 rgbi:0.0/0.0/0.9
which are black, red, green, and blue, respectively.  You can alter these
colors, or leave them unchanged and start defining colors at 05.  The largest
color number you define will be the last color index used; if more line colors
are needed, they will cycle back to color 01.  If you leave a gap in the
numbering (e.g., you define color 07 but not 05 or 06), then the undefined
colors will be fuliginous.

[Dec 2007] You can now specify the colors by using the special names 'green',
'red', 'blue', 'gold', and 'purple'.  Also, by using 3 or 6 digit hexadecimal
notation as in '#8888aa' for a blueish-gray color (6 digits) or '#0ac' for a
cyanish color (3 digits).  These are intended to make life a little simpler.

--------------------------
Variable: AFNI_1DPLOT_THIK (editable)
--------------------------
This numeric variable lets you control the thickness of lines drawn in the
1dplot-style windows.  The units are in terms of the width of the entire
plot, so that a value of 0.005 is 'reasonable'; 0.01 will be fairly thick
lines, and 0.02 will be too thick for most purposes.

----------------------------
Variable: AFNI_1DPLOT_IMSIZE
----------------------------
This numeric variable sets the image size (in pixels across the screen) of
images saved via the '-png' or '-jpg' options of 1dplot, or images saved
when giving the '.png' or '.jpg' from 1dplot-style graphs.  The default
value is 1024.  Values over 2048 may give odd looking results, and will
be palpably slower to render.

---------------------------------
Variable: AFNI_SIEMENS_INTERLEAVE
---------------------------------
The old (pre-DICOM) Siemens .ima image mosaic format sometimes stores the
multi-slice EPI data in correct spatial order and sometimes in correct
time acquisition order.  In the latter case, the images are stored in
a spatially-interleaved fashion.  As far as I know, there is no way to
tell this from the .ima file header itself.  Therefore, if you have a
problem with such files, set this variable to YES to un-interleave the
images when to3d reads them.  One way to tell if the images need to be
un-interleaved is to do
  afni -im fred.ima
then look at the images in an Axial image viewer.  If the slices make up
a single coherent volume, then they are NOT interleaved.  If the slices
look like they make up 2 separate brain volumes, then they need to be
un-interleaved, and you need to set this variable to YES.

-----------------------------
Variable: AFNI_TRY_DICOM_LAST
-----------------------------
When to3d tries to read an image file, it guesses the format from the
filename.  However, this doesn't always work.  In particular, DICOM files
don't have any fixed filename suffix or prefix.  If all else fails, to3d
normally tries to read a file as a DICOM file, and as a last resort, as
a flat binary file.  However, if a file is NOT a DICOM file, the DICOM
reading function will print out a lot of error messages, since there is
also no standard internal marker in all DICOM files that identify them.
Most people don't like all these messages (perhaps hundreds per file),
even if the program then successfully reads their flat binary files.

If this YES/NO variable is set to YES, then the normal last-resort order
of reading described above is reversed.  If to3d can't read the file any
other way, it will try it as a flat binary file.  If that fails, then
DICOM will be the ultimate resort, instead of being the penultimate
resort that it is by default.  This may help elide some error messages.
However, if you have a DICOM file that is exactly 131072 bytes long
(for example), then it will be interpreted as a headerless 256x256 image
of shorts, instead of whatever it really is.  So only set this variable
to YES if necessary!

-----------------------------
Variable: AFNI_THRESH_BIGSTEP
-----------------------------
The AFNI threshold sliders (in the Define Overlay control panels and the
Render Dataset plugins) are divided into 10000 steps from bottom to top.
If you click in the trough or use the PageUp/PageDown keys, the default
action is to move the slider 10 of the steps at once.  (The up and down
arrow keys move 1 step at a time.)  You can change this big step from the
default of 10 to any value between 1 and 1000 by setting this environment
variable; for example
  setenv AFNI_THRESH_BIGSTEP 100
will move the slider 1% of its height per PageUp/PageDown key or mouse click.

--------------------------
Variable: AFNI_THRESH_AUTO (editable)
--------------------------
If this YES/NO variable is set to YES, then whenever you switch overlay datasets,
the function threshold slider will automatically change to some value that may
be appropriate for the values in the new dataset.  [This is for Ziad!]

------------------------------
Variable: AFNI_SNAPFILE_PREFIX
------------------------------
Image files saved with the "snapfile" (or "record to file") by default have
filenames of the form "S_000001.ppm".  The prefix "S" can be altered by
setting this environment variable; for example,
  setenv AFNI_SNAPFILE_PREFIX Elvis
will save snapfiles with names like "Elvis_000666.ppm".  You can view snapfiles
with the "aiv" ("AFNI Image Viewer") utility, the "xv" program, or many other
Unix utilities.

-------------------------------
Variable: AFNI_STARTUP_WARNINGS
-------------------------------
When the interactive AFNI program starts, it may pop up warnings about the
programming environment for which it was compiled.  At this time, there are
two such warning messages possible:
  LessTiff: AFNI will work with LessTif, but works better with Motif.
  Button-3: On Solaris 2.8, Button-3 popup menus don't work quite properly.
If you are tired of seeing these messages, set AFNI_STARTUP_WARNINGS to NO.

----------------------
Variable: AFNI_1D_TIME
----------------------
If this YES/NO variable is set to YES, then when a multicolumn .1D file is
read in as an AFNI dataset, the column variable is taken to be time, and
a time-dependent dataset is created.  The default is to create a bucket
dataset.  Note that each row is taken to be a separate 'voxel'.

-------------------------
Variable: AFNI_1D_TRANOUT
-------------------------
If this variable is set to YES, it affects the way 1D datasets are
written out from 3d* programs that are being used to process 1D files
as AFNI dataset.  If this variable is YES, AND if the output dataset
prefix ends in '.1D' or is the string '-' (meaning standard output),
then the output 1D file will be transposed and written so that the
time axis goes down the columns instead of across them.  If this
variable is NO, then the standard AFNI 1D-to-3D dataset convention is
followed: each row is a single voxel time series.  Example:
  3dDetrend -polort 1 -prefix - 1D:'3 4 5 4 3'\'
will write to the screen
           -0.8
            0.2
            1.2
            0.2
           -0.8
if AFNI_1D_TRANOUT is YES, but will write
 -0.8 0.2 1.2 0.2 -0.8
to stdout if AFNI_1D_TRANOUT is NO.

-------------------------
Variable: AFNI_1D_TIME_TR
-------------------------
If this is set, and AFNI_1D_TIME is YES, then this determines the TR (in
seconds) of a .1D file read in as an AFNI dataset.

------------------------
Variable: AFNI_3D_BINARY
------------------------
If this is set to YES, then .3D files are written by AFNI programs in
binary, rather than the default text mode.  Binary files will be more
compact (usually) and faster to read in.

--------------------------
Variable: AFNI_MAX_OPTMENU (editable)
--------------------------
This variable (default=255) sets the maximum number of entries allowed
in an AFNI "option menu" -- these are the buttons that popup a menu
of values from which to choose, and which also let you popup a text
list chooser by right-clicking in the menu's label.  (Example: the
sub-brick option menus "Anat", "Func", "Thr" on the "Define Overlay"
control panel.)

Some computer systems may crash when an option menu gets too big.
That's why there is a default limit in AFNI of 255 entries.  However,
if you have a bucket dataset with more than 255 sub-bricks, this makes
it impossible to view the later data volumes.  If this problem arises,
you can try setting this environment variable to a larger limit (e.g.,
99999 would take care of all currently imaginable cases).

---------------------------------
Variable: AFNI_VALUE_LABEL_DTABLE
---------------------------------
This variable sets a filename that holds a default value-label table
for the Draw Dataset plugin.  A sample file is shown below:

   <VALUE_LABEL_DTABLE
     ni_type="2*String"
     ni_dimen="3" >
    "1" "elvis"
    "2" "presley"
    "3" "memphis"
   </VALUE_LABEL_DTABLE>

The 'ni_dimen' attribute is the number of value-label pairs; in the
  above example it is 3.
Each value-label pair is shown on a separate line.  The values and
  labels are strings, enclosed in quote characters.  There should be
  exactly as many value-label pairs as specified in 'ni_dimen'.
If you really want to put a double quote character " in a label,
  you can enclose the label in single forward quotes ' instead.
When you 'Save' a drawn dataset from the Draw Dataset plugin, the
  .HEAD file attribute VALUE_LABEL_DTABLE will contain a table in
  exactly this XML-based format.

-------------------------------
Variable: AFNI_STROKE_THRESHOLD (editable)
-------------------------------
If you press Button-1 in an image window, and then move it left or
right ("stroke it") before releasing the button, the grayscale mapping
changes in the same way as if you pressed the 'c' button up and the 'b'
button down.  This variable sets the threshold for the stroking movement
size in pixels; a movement of this number of pixels rightwards corresponds
to one press of 'c' up and 'b' down, while a leftwards movement is like
one press of 'c' down and 'b' up.  Larger movements make larger adjustments.

A larger threshold makes the stroking less sensitive; a smaller threshold
makes it more sensitive.  The value you choose will depend on your personal
taste.  The default is 32 pixels, which is the flavor I prefer.  If you set
this variable to 0, then the stroking function is disabled.

-------------------------------
Variable: AFNI_STROKE_AUTOPLOT (editable)
-------------------------------
If this variable is set to YES, then the graymap-versus-data value plot
(manually controlled by "Display Graymap Plot") is automatically popped
up when the grayscale mapping is altered by using the stroking feature
described above.  When the stroke is finished, the plot will pop down.
N.B.: when the 'Draw Dataset' plugin is active, this option is disabled
temporarily.

-----------------------------
Variable: AFNI_IMAGE_MINTOMAX (editable)
-----------------------------
If this variable is set to YES, then image viewer windows will be set
to the "Min-to-Max" state rather than the default "2%-to-98%" state
when they are opened.  If you set this in the "Edit Environment"
control, it only affects image viewer windows opened after that point.

----------------------------
Variable: AFNI_IMAGE_CLIPPED (editable)
----------------------------
If this variable is set to YES, then image viewer windows will be set
to the "Clipped" state rather than the default "2%-to-98%" state
when they are opened.  If you set this in the "Edit Environment"
control, it only affects image viewer windows opened after that point.

----------------------------
Variable: AFNI_IMAGE_CLIPBOT (editable)
----------------------------
In the "Clipped" mode, the top level of the grayscale image is computed
as 3.11 times the 'cliplevel' as computed by the 3dClipLevel algorithm.
The bottom level is then a fraction of this top level -- by default, the
fraction is 0.25, but you can change this default by setting this variable
to a value between 0.0 and 0.5 (inclusive).  You can also use variable
AFNI_IMAGE_CLIPTOP to scale the default top level -- this variable can take
values between 0.6 and 1.9 (inclusive) -- the default is 1.0.

--------------------------------
Variable: AFNI_IMAGE_GLOBALRANGE (editable)
--------------------------------
If this variable is set to YES, then the image viewer windows will be
set to scale the bottom gray level to the minimum value in the 3D
volume and the top gray level to the maximum value in the 3D volume.
This setting overrides the "Min-to-Max" and "2%-to-98%" settings in
the "Disp" control panel.  This setting also applies to all image
viewers.  If you set this in the "Edit Environment" control, it will
apply to all open image viewers immediately, as well as to any image
viewers opened later.
  It is important to realize that if you use the 'Display Range'
popup to set the bot-top range for the grayscale, these settings
will override the global range UNTIL you switch datasets or switch
sub-bricks within a dataset.  At that point, the global range for
the new volume will be enforced.  This change can be confusing.
Therefore, the info label beneath the slider shows the source of
the bot-top grayscale values:
  [2%-98%]  = from the 2% to 98% points on the slice histogram
  [Min2Max] = from the 0% to 100% points on the slice histogram
  [Glob]    = set from the entire volume min and max values
  [User]    = set by the user from 'Display Range'
  absent    = not applicable (e.g., underlay image is RGB)
The popup 'hint' for the grayscale bar shows the current values
of the bot-top range, if you want to know what numbers correspond
to the image at which you are gazing so fondly.
  Finally, note that when a montage is built, the number-to-grayscale
algorithm is applied to each slice separately, and then the montage
is assembled.  For [2%-98%] and [Min2Max], this fact means that each
slice will (probably) have a separate grayscale conversion range.

----------------------------
Variable: AFNI_DRAW_UNDOSIZE (editable)
----------------------------
This variable sets the size (in units of Megabytes) of the Undo/Redo
buffer in the Draw Dataset plugin.  The default value is 6.  If you
are short on memory, you could set this to 1.  If you are running out
of undo levels, you could set this to a larger value; however, this
would only be needed if you are drawing huge 3D swaths of data at a
time (e.g., using the 3D sphere option with a large radius).

---------------------
Variable: AFNI_SPEECH (editable)
---------------------
If this YES/NO variable is set to NO, then the AFNI speech synthesis
is disabled.  At the current time (Nov 2003), only the Mac OS X 10.3
version of AFNI uses speech synthesis in any way.  And that's just
for fun.

------------------------------
Variable: AFNI_IMAGE_ZEROCOLOR
------------------------------
This variable, if set to the string name of one of the colors in the
color chooser menus (e.g., "Black"), will result in voxels whose value
is 0 being set to this color in the slice viewing windows (except when
viewing RGB images).  The main function is to avoid having to use the
"Choose Zero Color" menu all the time, especially when you use the "Swap"
feature to invert the grayscale map (e.g., to make a T2 weighted image
look sort of like a T1 weighted image).

----------------------------
Variable: AFNI_MPEG_DATASETS
----------------------------
This variable can be used to allow MPEG files to be read in as AFNI datasets.
Such datasets are inherently 3 dimensional.  How they will be organized inside
AFNI depends on the setting of this variable.  The options are:
  SPACE = the frame sequence number will be the z-axis
  TIME  = the frame sequence number will be the time axis
  NO    = MPEG files won't be read as AFNI datasets
          (they can still be read as images into to3d, aiv, etc.)
If this variable is NOT set to anything, then it is the same as SPACE.

MPEG filenames input to AFNI programs (as sources of images or as datasets)
must end in ".mpg", ".MPG", ".mpeg", or ".MPEG".  MPEG datasets will be read
so that the individal images are displayed in an Axial image window.

---------------------------
Variable: AFNI_MPEG_GRAYIZE
---------------------------
If this YES/NO variable is set to YES, then MPEG files read into AFNI,
to3d, or aiv will be converted to grayscale, even if the images in
the movie are in color.

--------------------------
Variable: AFNI_VIDEO_DELAY (editable)
--------------------------
This is the number of milliseconds the AFNI waits between drawing new
images when the 'V' or 'v' keys are pressed in an image (or graph)
window.  The default value is 1, which is faster than video can be
displayed anyway.  Set this to a larger value (e.g, 100) to slow down
the image redraw rate.

----------------------------
Variable: AFNI_IMAGE_ENTROPY (editable)
----------------------------
If this numeric variable is set, this is the entropy of an image below
which the 2%-98% image scaling will be disabled, and min-to-max will
be used instead.  The units are bits/byte; a useful threshold seems to
be in the range (0.2,0.5).  For images that only have a few values
different from 0, the 2%-98% scaling can produce weird artifacts.  Such
images will also have a very low entropy.  Since this variable can be
changed interactively from the Edit Environment controls, you can play
with it to see how it affects your images.

----------------------------
Variable: AFNI_LOGO16 (etc.)
----------------------------
If this variable is set to YES, then the 'AFNI' background logo used in
the controller and image windows will be enabled.  By default, it is off.
You can control the colors of this logo by the following variables:
  AFNI_LOGO16_FOREGROUND_x
  AFNI_LOGO16_BACKGROUND_x
where 'x' is 'A', 'B', 'C', etc., for the various controller labels.
If AFNI_LOGO16_BACKGROUND_x isn't set, then AFNI_LOGO16_BACKGROUND
(with no suffix) is checked as an alternate.  The values of these
variables should be the names of one of the labels on the color chooser
menus (e.g., the "Xhairs Color" menu).  You can use these variables to
make the windows for the various controllers somewhat distinct in
appearance.  If these color variables are not set at all, then AFNI
uses some colors of my choosing for this purpose.

----------------------------------
Variable: AFNI_COLORIZE_CONTROLLER
----------------------------------
If this variable is set to YES, then the background of the AFNI controllers
and image viewers will be colorized.  The default state is that they are not
colorized.

--------------------------
Variable: AFNI_THRESH_LOCK (editable)
--------------------------
This variable can be used to lock the Define Overlay threshold sliders
together.  There are three possibilities:
  NO (the default) => each controller's slider is independent
  VALUE            => the numerical value on each slider will be the same
  P-VALUE          => the p-value for each slider will be the same
This locking only applies to AFNI controllers that are Lock-ed together
(cf. AFNI_ALWAYS_LOCK and the Define Datamode->Lock menu).  If p-values
are locked, this lock will also only apply to controllers whose current
Threshold sub-brick has a known statistical distribution.

When you drag a locked threshold slider, the other one will only change
when you release the mouse button -- they won't slide in tandem, but will
just jump to the final value.

------------------------
Variable: AFNI_PBAR_LOCK (editable)
------------------------
If this variable is set to YES, then the Define Overlay color bars
(the "pbars") of AFNI controllers that are Lock-ed together will be
coordinated.  Changes to one locked pbar will be reflected in the
others immediately.

----------------------------
Variable: AFNI_IMAGE_ZOOM_NN (editable)
----------------------------
If this variable is set to YES, then image viewer windows will use
nearest neighbor interpolation for zooming.  The default is linear
interpolation, which produces smoother-looking images.  However, some
people want to see the actual data values represented in the window,
not some fancy-schmancy interpolated values designed to look good but
in fact making a mockery of a sham of a mockery of a travesty of two
mockeries of a sham of reality.

------------------------------
Variable: AFNI_DISABLE_CURSORS
------------------------------
If this variable is set to YES, then AFNI will not try to change the X11
cursor shape.  This feature is available because it seems that sometimes
particular X11 installations choices of cursor and AFNI's choices don't
work together well.  If you have unpleasant cursors in AFNI (e.g., an X),
try setting this variable to YES.

-----------------------------
Variable: AFNI_SLAVE_FUNCTIME (editable)
-----------------------------
When the underlay and overlay datasets both are time-dependent, switching
the time index will change both the underlay and overlay sub-bricks.  If
you want the time index control to change ONLY the underlay sub-brick,
then set this variable to NO.

----------------------------
Variable: AFNI_SLAVE_THRTIME (editable)
----------------------------
When the underlay and overlay datasets both are time-dependent, switching
the time index will change both the underlay and overlay sub-bricks, but
NOT the threshold sub-brick.  If you want the time index control to change
the threshold sub-brick, then set this variable to YES.

--------------------------------
Variable: AFNI_SLAVE_BUCKETS_TOO
--------------------------------
Set this to YES if you want to make changing the time index in the underlay
dataset change the sub-brick index in the overlay dataset even when the
overlay is a 'bucket' dataset without a time axis.

----------------------------
Variable: AFNI_CLICK_MESSAGE
----------------------------
If this veriable is set to NO, then the string
  [---------------]
  [ Click in Text ]
  [ to Pop Down!! ]
will NOT be appended to the very first popup message window that AFNI
creates.  This message was added because some people do not realize
that the way to get rid of these popups (before they vanish on their
own after 30 seconds) is to click in them.  You know who you are.
However, if you are advanced enough to read this file, then you probably
aren't one of THEM.

-----------------------------
Variable: AFNI_X11_REDECORATE (editable)
-----------------------------
By default, AFNI tries to change some of the "decorations" (control buttons)
on some of the windows it creates (e.g., removing resize handles).  If you
don't want this to happen, set this variable to NO.  This variable only
has an effect on windows created AFTER it is set, so if you change this
interactively in the Edit Environment plugin, it will not affect existing
windows.  Normally, you would want to set this in your .afnirc file.

-------------------------------
Variable: AFNI_IMAGE_SAVESQUARE
-------------------------------
YES/NO: Forces images (from the image view "Save" button) to be saved with
square pixels, even if they are stored with nonsquare pixels.

-------------------------------
Variable: AFNI_BUCKET_LABELSIZE
-------------------------------
THIS VARIABLE HAS BEEN REMOVED FROM AFNI.

Formerly, it was used to set the width of the "ULay", "OLay", and "Thr" menu
choosers on the "Define Overlay" control panel.  As of 03 May 2005, AFNI now
calculates the default width based on the longest sub-brick label input
for each dataset.

-------------------------
Variable: AFNI_MAX_1DSIZE
-------------------------
Sets the maximum size (in bytes) of each 1D file that will be automatically
loaded when AFNI starts.  The default is 123 Kbytes.  The intention is to
prevent loading of very large files that are not intended to be used for
graphing/FIMming purposes.

---------------------------
Variable: AFNI_TITLE_LABEL2 (editable)
---------------------------
If this YES/NO variable is YES, then the AFNI window titlebars will show
the 'label2' field from the AFNI dataset .HEAD file, rather than the
dataset filename.  If the label2 field is set to a nontrivial value,
that is.  You can set the label2 field with the 3drefit command.

-------------------------------
Variable: AFNI_SHOW_SURF_POPUPS
-------------------------------
If this YES/NO variable is set to YES, then when AFNI receives surface
nodes, triangles or normals from suma, a popup message will be displayed.
Otherwise, the message will be send to stderr (on the terminal window).

-------------------------------
Variable: AFNI_KILL_SURF_POPUPS
-------------------------------
If this YES/NO variable is set to YES, then when AFNI receives surface
nodes, triangles or normals from suma, no messages will be displayed,
either in a popup or stderr.  Note that if errors occur, popups will
still be shown; this just turns off the normal information messages.
N.B.: If AFNI_SHOW_SURF_POPUPS is YES, then it wins over
      AFNI_KILL_SURF_POPUPS being YES.  If neither is set, then
      messages are displayed to stderr.

-----------------------------
Variable: AFNI_EDGIZE_OVERLAY (editable)
-----------------------------
If set to YES, then the color overlays in the image windows will only
have their edge pixels displayed.  That is, each 'blob' will be hollowed
out, leaving only its edges.  If you do this, you probably want to make
the color overlay opaque, so that the results are easily seen.

--------------------------
Variable: AFNI_NIFTI_DEBUG (editable)
--------------------------
This integral variable determines the debug level used by the nifti_io
library functions.  If set to 0, only errors are reported by the library.
The maximum debug level used is currently 4.  Note that if this is changed
from within AFNI, a 'Rescan: This' operation should probably be performed,
which will force a re-reading of the datasets and so force an elicitation
of the NIfTI debug messages (for .nii files, that is).

--------------------------
Variable: AFNI_NIFTI_NOEXT
--------------------------
When writing a '.nii' (or '.nii.gz') file from an AFNI program, normally
a NIfTI-1.1 extension field with some extra AFNI header information is
written into the output file.  If you set this variable to YES, then
this extension is not written, which will make the output be a 'pure'
NIfTI-1.1 file.  Only use this if absolutely necessary.  You can also
use the 'nifti_tool' program to strip extension data from a NIfTI-1.1
dataset file.

---------------------------
Variable: AFNI_OVERLAY_ZERO (editable)
---------------------------
If set to YES, this variable indicates that voxels in the overlay dataset
that have the numerical value of 0 will get colored when the Inten color
scale on the Define Datamode panel indicates that 0 has a color that isn't
"none".  The default way that AFNI works is NOT to colorize voxels that
are 0, even if they should otherwise get a color.

---------------------------
Variable: NIML_TRUSTHOST_xx
---------------------------
These environment variables ('xx' = '01', '02', ..., '99') set the names
and/or addresses of external computer hosts to trust with NIML TCP/IP
connections, which are how AFNI and SUMA communicate.  Should only be
necessary to use these if you are using AFNI and SUMA on different
machines.  Connections from machines not on the trusted list will be
rejected, for the sake of security.  The 'localhost' or 127.0.0.1 address
and local class B network 192.168.0.* addresses are always trusted.

---------------------------
Variable: AFNI_DONT_LOGFILE
---------------------------
Most AFNI programs write a copy of their command line to a file in your
home directory named ".afni.log".  If you do NOT want the log to be
kept, set this environment variable to YES.  The purpose of the log
is for you to be able to look back and see what AFNI commands you used
in the past.  However, if you are doing a vast number of commands inside
a script, the log file might eventually become gigantic (the Kevin Murphy
effect).

-------------------------
Variable: AFNI_WRITE_NIML
-------------------------
If this variable is set to YES, then AFNI .HEAD files will be written in
the new NIML (XML subset) format, rather than the 'classic' format.  The
volumetric image data is still in the pure binary .BRIK file, not XML-ified
in any way.  At present (Jun 2005) this format is experimental, but will
someday soon become the default.

---------------------------------
Variable: AFNI_ALLOW_MILLISECONDS
---------------------------------
The TR value (time step) in 3D+time datasets created with to3d can be flagged
as being in units of milliseconds (ms) or seconds (s).  This situation is
unfortunate, as some AFNI programs assume that the units are always s, which
doesn't work well when the TR is actually in ms.  On 15 Aug 2005, AFNI dataset
I/O was modified to only write out TR in s units, and to convert ms units
to s units on input.  If you absolutely need to store TR in ms, then you
must set this environment variable to YES.  I strongly recommend against
such a setting, but recall the AFNI philosophy: "provide mechanism, not
policy" -- in other words, if you want to shoot yourself in the foot, go
right ahead.  This variable is just the safety on the revolver.

------------------------------
Variable: AFNI_TTATLAS_CAUTION (editable)
------------------------------
If this YES/NO variable is set to NO, then the warning about the potential
errors in the "Where am I?" popup will not appear.  This is purely for
cosmetic purposes, Ziad.

--------------------------
Variable: AFNI_AUTO_RESCAN
--------------------------
If this YES/NO variable is set to YES, then the interactive AFNI program
will rescan all session directories every 15 seconds for new datasets.
Basically, this is just a way for you to avoid pressing the 'Rescan'
buttons.  Note that if AFNI_AUTO_RESCAN is enabled, then the rescan
method will be 'Add', not 'Replace', no matter what you set variable
AFNI_RESCAN_METHOD to.

-------------------------------
Variable: AFNI_RESCAN_AT_SWITCH
-------------------------------
If this YES/NO variable is set to YES, then the interactive AFNI program
will rescan all session directories everytime you click on either of the
'Overlay' or 'Underlay' buttons. Basically, this is just another way for
you to avoid pressing the 'Rescan' buttons.  (Unlike with AFNI_AUTO_RESCAN,
the AFNI_RESCAN_METHOD settings are respected.)

--------------------------
Variable: AFNI_WEB_BROWSER
--------------------------
This variable should be set to the full executable path to a Web browser,
as in
  setenv AFNI_WEB_BROWSER /usr/bin/mozilla
If it is not set, AFNI will scan your path to see if it can find a browser,
looking for "firefox", "mozilla", "netscape", and "opera" (in that order).
If a browser is found, or set, then the 'hidden' popup menu (in the blank
square to the right of the 'done' button) will have a menu item to open it.

----------------------------
Variable: AFNI_JPEG_COMPRESS
----------------------------
This variable determines the compression quality of JPEG files saved in
the AFNI GUI and 3dDeconvolve. Its value can be set to an integer from
1 to 100. If not set, the default value is 95%.

---------------------------
Variable: AFNI_NLFIM_METHOD
---------------------------
Can be used to set the optimization method using in the NLfit plugin
(not in 3dNLfim).  The methods available are
  SIMPLEX (the default)
  POWELL  (the NEWUOA method)
  BOTH    (use both methods, choose the 'best' result)

----------------------------
Variable: AFNI_OVERLAY_ONTOP
----------------------------
If this variable is set to YES, then the 'Overlay' button will be above
the 'Underlay' button on the AFNI control panel.  The default, from the
olden days, is to have the 'Underlay' button above the 'Overlay' button,
which some people find confusing.

-----------------------------
Variable: AFNI_DATASET_BROWSE (editable)
-----------------------------
If this variable is set to YES, then when you 'browse' through a dataset
chooser ('Overlay' or 'Underlay' list) with the mouse or arrow keys, then
as a dataset is selected in the list, AFNI will immediately switch to
viewing that dataset.  This can be convenient for scrolling through datasets,
but can also consume memory and CPU time very quickly.

------------------------------
Variable: AFNI_DISABLE_TEAROFF
------------------------------
If this variable is set to YES, then the AFNI GUI will not allow popup or
popdown menus to be 'torn off'.  The default is to enable tear off for most
menus, but this may cause bad things on some platforms (like program death).

-------------------------------
Variable: AFNI_PLUGOUT_TCP_BASE
-------------------------------
This integer will override the base TCP port used by afni to listen for
plugouts.  This allows multiple instances of afni on one machine, where
each can listen for plugouts.  Valid port numbers are 1024..65535.

-----------------------------------
Variable: AFNI_IMAGE_TICK_DIV_IN_MM (editable)
-----------------------------------
If this YES/NO variable is set to YES, then the Tick Div. value in an
image window will be interpreted as a separation distance, in mm, as
opposed to the number of tick divisions along each edge.  In the YES case,
a larger value would produce fewer ticks, as they would be farther apart.
In the NO case, a larger value will produce more tick marks.  Tick marks
are controlled from the Button 3 popup menu attached to the grayscale
intensity bar in an image viewer.

----------------------------
Variable: AFNI_IMAGRA_CLOSER
----------------------------
If this YES/NO variable is set to YES, then when you click in an 'Image'
or 'Graph' button for a viewer window that is already open (so the button
is displayed in inverted colors), then the corresponding viewer window
will close.  The default action is to try to raise the viewer window to
the front, but some window managers (I'm looking at you, FC5) don't allow
this action.  So this provides a way to kill the window, at least, if you've
lost it in desktop hell somewhere.

-------------------------
Variable: AFNI_DECONFLICT
-------------------------
When AFNI programs write datasets to disk, they will check whether the
output filename already exists.  If it does, the AFNI programs will act
based on the possible values of AFNI_DECONFLICT as follows:
    NO/<none>   : do not modify the name or overwrite the file, but
                  inform the user of the conflict, and exit
    YES         : modify the filename, as stated below
    OVERWRITE   : do not modify the filename, overwrite the dataset
If AFNI_DECONFLICT is YES, then the filename will be changed to one that
does not conflict with any existing file.  For example 'fred+orig' could
be changed to 'fred_AA1+orig'.

The default behavior is as 'NO', not to deconflict, but to exit.
Some programs supply their own default.

--------------------------
Variable: AFNI_SEE_OVERLAY
--------------------------
If this variable is set to YES, then the 'See Overlay' button will be turned
on when a new AFNI controller is opened.

------------------------------
Variable: AFNI_INDEX_SCROLLREV
------------------------------
If this variable is set to YES, then the default direction of image slice
and time index scrolling will be reversed in the image and graph viewers,
respectively.

-----------------------------
Variable: AFNI_CLUSTER_PREFIX
-----------------------------
This variable sets the prefix for 'Save' timeseries 1D files from the
'Clusterize' report panel.  The default string is "Clust".  The value
of this variable will be loaded into the cluster Rpt window text entry
field, and the prefix can be edited there by the users when it comes
time to save files.

-----------------------------
Variable: AFNI_CLUSTER_SCROLL
-----------------------------
If this variable is NO, then the 'Clusterize' report will not be given
scrollbars.  The default is to give it scroll bars (i.e., YES).

-----------------------------
Variable: AFNI_CLUSTER_REPMAX  (editable)
-----------------------------
This numeric variable (between 10 and 9999, inclusive) sets the maximum
number of clusters that will be reported in a 'Clusterize' report panel,
if scroll bars are turned off by AFNI_CLUSTER_SCROLL. The default value
is 15.  If scroll bars are turned on, then the maximum number of clusters
shown defaults to 999, but can be increased to 9999 if you are completely
mad, or are named Shruti.  If scroll bars are turned off, then you probably
don't want to make this very big, since the report window would become
taller than your monitor, and that would be hard to deal with.

----------------------------
Variable: AFNI_STRLIST_INDEX
----------------------------
If this variable is set to NO, then the new [12 Oct 2007] 'Index' selector
at the bottom of a string-list chooser (e.g., the 'Overlay' button popup
window) will NOT be shown.

-----------------------------
Variable: AFNI_HISTOG_MAXDSET
-----------------------------
If this variable is set to a numeric value between 4 and 9 (inclusive),
then the number of Source datasets in the 'Histogram: Multi' plugin
will be set to this value.  The default number of Source datasets is 3 --
this variable allows you to increase that setting.

----------------------------
Variable: AFNI_SIGQUIT_DELAY
----------------------------
This numeric variable (between 1 and 30) sets the number of seconds AFNI
will delay before exiting after a SIGQUIT signal is delivered to the process.
The default delay is 5 seconds.  If you deliver a SIGALRM signal, AFNI will
exit immediately.  If you don't know what Unix signals are, then don't pay
any attention to this subject!

--------------------------------
Variable: AFNI_NEVER_SAY_GOODBYE
--------------------------------
If this variable is set to YES, then the AFNI 'goodbye' messages won't
be printed when the program exits.  For the grumpy people out there
(you know who I'm talking about, don't you, Daniel?).

--------------------------------
Variable: AFNI_NEWSESSION_SWITCH
--------------------------------
If this variable is set to NO, then AFNI will not automatically switch
to a new session after that session is read in using the 'Read Sess'
button on the Datamode control panel.

-------------------------------
Variable: AFNI_FLASH_VIEWSWITCH
-------------------------------
If you switch sessions, underlay, or overlay, it can happen that the
coordinate system might be forced to switch from +orig to +tlrc
(for example) because there is no dataset to view in the +orig system.
Normally, AFNI flashes the view switch buttons on and off a few times
to let you know this is happening (this is the Adam Thomas feature).
You can turn this feature off, by setting this variable to NO.

-------------------------
Variable: AFNI_SHELL_GLOB
-------------------------
'Globbing' is the Unix jargon for filename wildcard expansion.  AFNI programs
do globbing at various points, using an adaptation of a function from the
csh shell.  This function has been reported to fail on Mac OS X Server 10.5
on network mounted directories.  If you set this variable to YES, then globbing
will instead be done using the shell directly (via popen and ls).  You should
only set this variable if you really need it, and understand the issue!
[For Graham Wideman]

----------------------------------
Variable: AFNI_IGNORE_BRICK_FLTFAC
----------------------------------
Under some very rare circumstances, you might want to ignore the brick scaling
factors.  Set this variable to YES to do so.  WARNING: this is dangerous, so
be sure to unset this variable when you are done.  Sample usage:
  3dBrickStat -DAFNI_IGNORE_BRICK_FLTFAC=YES -max fred+orig

----------------------------------------------------------------------
--- variables specific to NIML I/O
----------------------------------------------------------------------

-----------------------------------
Variable: AFNI_NIML_DEBUG
-----------------------------------
This integer sets the debugging level in some niml I/O routines, particularly
those in thd_niml.c.  Currently used values range from 0 to 3.

-----------------------------------
Variable: AFNI_NSD_ADD_NODES
-----------------------------------
If this YES/NO variable is set to YES, then when a NI_SURF_DSET dataset
is written to disk, if it has no node list attribute, a default list will
be created.

-----------------------------------
Variable: AFNI_NSD_TO_FLOAT
-----------------------------------
If this YES/NO variable is set to NO, then any necessary conversion of
NI_SURF_DSET datasets to type float will be blocked.  Otherwise, all such
datasets will be written as float.

-----------------------------------
Variable: AFNI_NIML_TEXT_DATA
-----------------------------------
If this YES/NO variable is set to YES, then NI_SURF_DSET datasets will be
written with data in text format.  Otherwise, data will be in binary.

-----------------------------
Variable: AFNI_SIMPLE_HISTORY
-----------------------------
A few programs (particularly 3dcalc) create a complicated history note
in the output dataset header, by including the history of all inputs.
This history can become inordinately long and pointless when 3calc is
run in a long chain of calculations.  Setting this variable to YES will
turn off this cumulation of all histories, and may make your dataset
headers more manageable.

-------------------------------------------
Variable: AFNI_NIML_BUFSIZE or NIML_BUFSIZE
-------------------------------------------
This variable sets the number of bytes used as a memory buffer for
NIML dataset input.  If you are inputting gigantic headers or gigantic
String data components (I'm looking at YOU, Ziad), then you may want
to increase this past its default size of 255*1024=261120.

----------------------------------------------------------------------
--- END: variables specific to NIML I/O
----------------------------------------------------------------------

----------------------------
Variable: AFNI_GIFTI_VERB
----------------------------
This integer sets the verbose level in the gifti I/O library routines.
Level 1 is the default, 0 is "quiet", and values go up to 7.

----------------------------
Variable: AFNI_DATASETN_NMAX
----------------------------
This numeric variable, if set, lets you expand the number of dataset
lines in the 'Dataset#N' plugin from the default of 9 up to a max of 49.
(This one is for Shruti.)

----------------------------
Variable: AFNI_WRITE_1D_AS_PREFIX
----------------------------
If this variable is set to YES, then 1D formatted files will be written
to the file based on the given prefix, rather than to an automatic 1D file.
This allows writing surface files to NIfTI format, for example.

=============================================
| Robert W Cox, PhD                         |
| Scientific and Statistical Computing Core |
| National Institute of Mental Health       |
| National Institutes of Health             |
| Department of Health & Human Services     |
| United States of America                  |
| Earth, United Federation of Planets       |
=============================================

############################################################################
##### Variables that Specifically Affect the Operation of 3dDeconvolve #####
############################################################################

-----------------------------------
Variable: AFNI_3dDeconvolve_GOFORIT
-----------------------------------
If this variable is set to YES, then 3dDeconvolve behaves as if you used the
'-GOFORIT' option on the command line -- that is, it will continue to run
even if it detects serious non-fatal problems with the problem setup.

--------------------------------
Variable: AFNI_3dDeconvolve_NIML
--------------------------------
3dDeconvolve outputs the regression matrix 'X' into a file formatted in
the 'NIML' .1D format -- with an XML-style header in '#' comments at the
start of the file.  If you DON'T want this format, just plain numbers,
set this variable to NO.

----------------------------------
Variable: AFNI_3dDeconvolve_extend
----------------------------------
If you input a stimulus time series (via the -stim_file option) to
3dDeconvolve that is shorter than needed for the regression analysis, the
program will normally print a warning message and extend the time series
with zero values to the needed length.  If you would rather have the program
stop if it detects this problem (the behavior before 22 Oct 2003), then set
this environment variable to NO.

---------------------------------
Variable: AFNI_3dDeconvolve_nodup
---------------------------------
If this variable is set to YES, then if the 3dDeconvolve program detects
duplicate input stimulus filenames or duplicate regressors, the program
will fail (with an error message) rather than attempt to continue.

-----------------------------------------
Variable: AFNI_3dDeconvolve_nodata_extras
-----------------------------------------
When using the -nodata option in 3dDeconvolve, the default printout gives
the 'normalized standard deviation' for each stimulus parameter.  If you
set this variable to YES, then the printout will include the -polort
baseline parameters as well, and also the L2 norm of each column in
the regression matrix.

-----------------------------------
Variable: AFNI_3dDeconvolve_oneline
-----------------------------------
3dDeconvolve outputs a command line for running the cognate 3dREMLfit
program.  By default, this command line is line broken with '\'
characters for printing beauty.  If you want this command line
to be all on one physical output line, for convenience in automatic
extraction (e.g., via grep), then set this variable to YES before
running the program.

--------------------------
Variable: AFNI_XJPEG_COLOR
--------------------------
Determines the color of the lines drawn between the column boxes in the
output from the -xjpeg option to 3dDeconvolve.  The color format is
"rgbi:rf/gf/bf", where each value rf,gf,bf is a number between 0.0 and 1.0
(inclusive); for example, yellow would be "rgbi:1.0/1.0/0.0".  As a
special case, if this value is the string "none" or "NONE", then these
lines will not be drawn.

-------------------------
Variable: AFNI_XJPEG_IMXY
-------------------------
This variable determines the size of the image saved when via the -xjpeg
option to 3dDeconvolve.  It should be in the format AxB, where 'A' is the
number of pixels the image is to be wide (across the matrix rows) and 'B'
is the number of pixels high (down the columns); for example:
  setenv AFNI_XJPEG_IMXY 768x1024
which means to set the x-size (horizontal) to 768 pixels and the y-size
(vertical) to 1024 pixels.  These values are the default, by the way.

If the first value 'A' is negative and less than -1, its absolute value
is the number of pixels across PER ROW.  If the second value 'B' is
negative, its absolute value is the number of pixels down PER ROW.
(Usually there are many fewer columns than rows.)

-------------------------
Variable: AFNI_XSAVE_TEXT
-------------------------
If this YES/NO variable is set to YES, then the .xsave file created by
the "-xsave" option to 3dDeconvolve will be saved in text format.  The
default is a binary format, which preserves the full accuracy of the
matrices stored therein.  However, if you want to look at the .xsave
file yourself, the binary format is hard to grok.  Note that the two
forms are not quite equivalent, since the binary format stores the
exact matrices used internally in the program, whereas the ASCII format
stores only a decimal approximation of these matrices.

---------------------------
Variable: AFNI_GLTSYM_PRINT
---------------------------
If this YES/NO variable is set to YES, then the GLT matrices generated
in 3dDeconvolve by the "-gltsym" option will be printed to the screen
when the program starts up.

-----------------------
Variable: AFNI_FLOATIZE
-----------------------
If this YES/NO variable is set to YES, then 3dDeconvolve and 3dcalc
will write their outputs in floating point format (unless they are
forced to do otherwise with the '-datum short' type of option).  In
the future, other programs may also be affected by this variable.
Later [18 Nov 2008]: Now 3dANOVA, 3dANOVA2, and 3dANOVA3 will also
use this flag to determine if their outputs should be written in
float format.  For example:
  3dANOVA -DAFNI_FLOATIZE=YES ... other options ...

----------------------------
Variable: AFNI_AUTOMATIC_FDR
----------------------------
If this variable is set to NO, then the automatic computation of FDR
curves into headers output by 3dDeconvolve, 3dANOVA, 3dttest, and
3dNLfim will NOT be done.  Otherwise, the automatic FDR-ization of
these datasets will performed when the datasets are written to disk.
(You can always use '3drefit -addFDR' to add FDR curves to a dataset
header, for those sub-bricks marked as statistical parameters.)