2.5. List of all AFNI environment variables

2.5.1. Overview

You can set Unix environment variables to control AFNI behavior and defaults on your system. These allow you, Dear User, to set things like: crosshair colors; default colorbars; colormap ranges; left=left or left=right behavior in image panels; having labels appear; image background color; 1dplot characteristics; “locking” behaviors in the GUI; text editor for viewing help files with -hview (like emacs!); global dset and atlas paths; and sooo maaaany mooore.

These settings can be managed in several ways– for example, using setenv in tcsh or export in bash. Probably the easiest+best way to go would be to define a file called ~/.afnirc (i.e., a file in your computer’s home directory called “.afnirc”– note the dot) and store your variable definitions and settings there. In fact, as part of your installation instructions, you should have already created this file (in fact, one for each of afni and suma; we just present the options for the former here). If you don’t, you should check the setup instructions for quickly doing this.

2.5.2. Intro: Unix env vars 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.


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.


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”.


You can now set environment variables on the ‘afni’ command line; for example: afni -DAFNI_SESSTRAIL=3 -DAFNI_FUNC_ALPHA=YES 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]


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.


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.


You can allow the .afnirc file to re-set existing environment variables by setting environment variable AFNI_ENVIRON_RESET to YES.

2.5.3. Setting env variables in file ~/.afnirc

As of June, 1999, you can now set environment variables for an interactive AFNI run in the setup (~/.afnirc) file. This is provided as a convenience. An example:


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.) And the file is:

  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

2.5.4. Env vars: the looong list


Most AFNI programs output various messages prefixed by '++', '**', and
divers variations. If you are running several programs at once, you can
pre-pend a string to these prefixes to distinguish them in the output
terminal stream. For example, a csh script might look like so:
  foreach fred ( 1 2 3 4 )
    setenv AFNI_MESSAGE_PREFIX case$fred
    run_some_program -option $fred ... |& tee out${fred}.txt &


When AFNI programs print WARNING or ERROR messages, they normally
print the 'WARNING' or 'ERROR' label using inverted colors, to aid in
picking out these messages from other text on the screen. To turn
this feature off, set this environment variable to 'NO'.

AFNI_FONTSIZE [06 Nov 2018]

This variable can be used to set the AFNI controller font sizes.
It is a convenient way to avoid using the '-XXXfontsize' option.
The values this variable can take are:
   MINUS ==> smaller than normal fonts
   PLUS  ==> larger than normal fonts
   BIG   ==> much larger than normal fonts


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

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.


This variable should be the directory in which AFNI should search for
plugins, executable files, atlases, templates and atlas definition
files. See the atlas environment variable section below for more
details. 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. Take care to remove any slow or
non-existent directories from the PATH because these problems will cause
searches to fail or become excessively slow.


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.


Setting this variable to YES will allow all defined plugins to
be loaded. Otherwise, little-used plugins must be allowed one
at a time, using the next set of variable names.


Some plugins distributed with AFNI are not commonly used, and are
disabled by default. If you wish to turn one of these plugins
back on, set the corresponding environment variable to YES.
The list of these plugins is:
  --- somename ---     --- name in menu ---
  2DREGISTRATION       2D Registration
  3DCLUSTER            3D Cluster
  3DCORRELATION        3D Correlation
  3DDUMP98             3D Dump98
  3DEDIT               3D Edit
  3DEXTRACT            3D+t Extract
  3DREGISTRATION       3D Registration
  3DSTATISTIC          3D+t Statistic
  4DDUMP               4D Dump
  ASL                  ASL a3/d3
  BRIKCOMPRESSOR       BRIK Compressor
  COORDORDER           Coord Order
  DATASETCOPY          Dataset Copy
  DATASETDUP           Dataset Dup
  DATASETRENAME        Dataset Rename
  DECONVOLVE           Deconvolution
  DSETZEROPAD          Dset Zeropad
  FOURIER              Fourier
  GYRUSFINDER          Gyrus Finder
  HEMISUBTRACT         Hemi-subtract
  HILBERTDELAY98       Hilbert Delay98
  HISTOGRAMBFIT        Histogram: BFit
  L1FIT                L1_Fit & Dtr
  L2FIT                LSqFit & Dtr
  MASKCALC             maskcalc
  PERMUTATIONTEST      Permutation Test
  POWERSPECTRUM        Power Spectrum
  REORDER              Reorder
  ROIAVERAGE           ROI Average
  ROIPLOT              ROI Plot
  SINGLETRIALAVG       SingleTrial Avg
  THRESHOLD            Threshold
  TSGENERATE           TS Generate
  WAVELETS             Wavelets


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.


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


This numeric value sets the number of preview lines for the AFNI
*.tsv/*.csv (TCSV) file chooser. If you don't set this to a
positive value, then the default number of preview lines is 4.


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


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.


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
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).


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".


This variable is used to control automatic compression of .BRIK files
on output. The legal values are "COMPRESS", "GZIP", "BZIP2", "PIGZ",
which respectively invoke programs "compress", "gzip","bzip2" and
"pigz" (these 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

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


On some systems, the multi-threaded version of gzip -- program pigz --
can fail randomly. To prevent the use of pigz even if it is found,
set this variable to YES. Note that if you explicitly set
AFNI_COMPRESSOR to PIGZ, then AFNI_DONT_USE_PIGZ will be ignored. The
purpose of AFNI_DONT_USE_PIGZ is to prevent the automatic use of the
pigz program in cases where you don't provide AFNI_COMPRESSOR


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.)


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]


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, so they don't take up swap
space, which is for saving modified memory pages).

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!  [Oct 2010] Now I have 32 GB of RAM (more than Ziad - ha!),
and it's nice!

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.

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 setting affects
the coronal and axial image and graph viewers.


Setting this YES/NO variable to YES tells AFNI to display images with
the posterior side of the subject on the left side of the window. The
default mode is to display the anterior side of the subject on the
left side of the window. This setting affects the sagittal image and
graph viewers.


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.


Setting this YES/NO variable to YES tells AFNI to start up with
Time lock turned on. The Time Lock feature can be set manually
from the Lock menu on the Define Datamode panel.


Setting this YES/NO variable to YES tells AFNI to start up with
Zoom lock turned on. The Zoom Lock feature can be set manually
from the Lock menu on the Define Datamode panel.

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


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


(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.


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


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


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.


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.


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.


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.


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).


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


If this variable is YES, then the splash screen will close via 'melting'.


This sets an upper limit on the % Change that the FIM+ computation
will compute. For example


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.


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.


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.


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.


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


Some X11 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.
** NOTICE **
  As of 10 May 2018, this variable no longer has any effect. The
  enforcement never worked well, and so you now have to manage this
  problem manually. To fix the aspect ratio of an image viewer
  window, Left-click in the image intensity bar (right of the image)
  or press the 'a' key while the mouse cursor is over the image.


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.


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


As of 28 Apr 2010, the AFNI Talairach 'Define Markers' panel will no
longer be visible by default. To use this old feature, you must set
this variable to YES before running AFNI.


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).


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.


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
https://afni.nimh.nih.gov/afni/afni_faq.shtml#AnatParent .


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.)


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.)


If this YES/NO variable is set to YES, then the AFNI GUI will pop up a
warning just ONCE when an oblique dataset is encountered.


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.


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.


If this variable is set to YES, then AFNI's viewers will reset the
crosshair coordinate to the center of the dataset whenever a new
dataset or sub-brick is chosen. The only real reason to use this
feature is if you are scanning through a collection of datasets with
wildly different coordinates, so that the usual method of matching
(x,y,z) coordinates at such times gives useless results.


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).


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.


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.

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.


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:

 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.

If you do NOT have any layout file defined, then AFNI will choose
a layout for you that includes opening image viewers. Some people
find this very annoying. The simplest way to avoid this annoyance
is to set AFNI_LAYOUT_FILE to a name of a file that doesn't exist
(e.g., 'ElvisIsAliveOnPlanetZork'). The reason for this default
layout behavior (added Dec 2010) is that we received complaints
that novice users were finding AFNI too confusing on startup.
(Hard to believe, but true.)


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.


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.


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!


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).


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.


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.


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.


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.


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.


When the AFNI GUI starts, by default it opens all 3 image viewer
windows. If you do NOT want a particular one of these, set the
corresponding variable named above to NO. For finer control over
AFNI startup, see the AFNI_STARTUP_SCRIPT variable and README.driver.


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!


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.


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:

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

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.


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.


If this YES/NO variable is not set to NO, then 2D image files
(*.png and *.jpg) will be read as datasets when the interactive
AFNI program starts. That is, you have to set this variable explicitly
to NO if you do not want image files read into the AFNI GUI at
startup. Image files can be opened using the Axial image viewer.


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.


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.


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.


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.


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.)


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.


If this YES/NO variable is set to YES, then when AFNI starts, it will
look for the smallest dataset in the first session, and choose this
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.

The old behavior of this variable was to set the smallest dataset
marked as 'Anatomical' to be the underlay, and the smallest dataset
marked as 'Functional' to be the overlay. The new behavior just
sets both the underlay and overlay to be the smallest dataset.
If you want the old behavior, set this variable to the string 'OLD'.


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.


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 (i.e., in a template
space) 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 *.nii *.nii.gz
in the global session directory.

In my [RWC's] global session directory, there is one file:
which I copied there from the AFNI binaries download. In this way,
I always have available the human template which I use most often.

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 present).


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.


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.


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.


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
Of course, you can always change the global baseline from the
Opt->Baseline menu.

AFNI_GRAPH_CX2R (editable)

This variable determines how the AFNI time series graphing window
displays complex-valued datasets. The possible values are ABS, PHASE,
REAL, and IMAG. (Actually, only the first letter matters to the
program.)  The default method is ABS. (If you edit this method
interactively, the graph won't automatically be redrawn -- you'll have
to force a graph window redraw to see the effects.)


Formerly, this variable determined how the AFNI grapher displays sub-brick
labels on top of the Box graphs (from the 'Colors, Etc.' menu, or via
the 'B' keypress).
Now, the choice of if and where the labels appear is made directly in
the graph viewer menus.


This variable is the name of a font to use for text overlays in the
AFNI time series graph viewers. If this variable is not set, the
program has a list of fonts to try to load. If none of those can
be loaded (something I've never seen happen), text may not display.
For best results, this should be a fixed width font. To see a full
list of all X11 fonts available, use the system command 'xlsfonts'
(you probably want to pipe this output through 'more'). The first
default font is currently [Apr 2011] set to
For a font that is larger than the default, try 9x15bold or even
10x20, as in the command
  afni -DAFNI_GRAPH_FONT=9x15bold
The entire list of fonts that will be tried can be found in the
source code file display.h, in the string array tfont_hopefuls[].


If this variable is set to YES, then the 'threshold fade' feature
of the AFNI graph window is turned on for all graph viewers when
they open. Otherwise, you have to turn this feature on via the
'F' key or the toggle control in the Opt menu.


If set to YES, this variable allows the use of the following keystroke
sequence in the AFNI graph viewer:
  digit [digit ...]
The result is to immediately shift the graph matrix count (number of
sub-graphs) to the decimal integer expressed by the digits. For example:
will set the graph window to show a 7x7 matrix of sub-graphs. By default,
this is disabled, since it confuses some beginners -- until you press
the <Enter> key, the graph window will be unresponsive to other keys.


This variable lets you add a new Adaptive Mean filter to the 'Tran 1D'
transformations menu in the AFNI graph viewer. The built in adaptive
mean filter widths are 9 time points (plus/minus 4 about each value)
and 19 time points (plus/minus 9). If you define this variable to
be an odd integer larger than 9, not equal to 19, and less than 100,
then a new function labeled 'AdptMeanXX' will appear in the 'Tran 1D'
menu, where 'XX' is the width you choose here. This transformation
is mainly for 'fun' -- to smooth out a time series to see structure
obscured by noise. You can combine this function with the |FFT|
function using the 'Edit 1Dchain' item in the Datamode->Misc menu.


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.


This string defines the color used for overlaying surface nodes
transmitted from SUMA to AFNI. This applies to surface number 'xxx',
for xxx=001, 002, etc. If this is set to "none", then these boxes (at
each node near a slice) won't be plotted.
**NOTE** This variable, and the immediately following AFNI_SUMA_something
         variables, can be set interactively from the 'Control Surface'
         chooser window in the AFNI GUI.
**NOTE** The colors allowed for surface display in AFNI are chosen via
         AFNI's color chooser menu. So no matter what color you specify
         in one of these AFNI_SUMA_something variables, it will be mapped
         to be the closest color on the color chooser menu.


This string defines the color used for overlaying surfaces transmitted
from SUMA to AFNI. This applies to surface number 'xxx', for xxx=001,
002, etc. If this is set to "none", then these lines (intersections
of surfaces with slices) won't be plotted.

In the special case that xxx=DEF, then the supplied color becomes
'default' for all lines. Individual line colors can still be set by
additional variables with xxx=001, 002, etc. being set.


This variable is similar to AFNI_SUMA_LINECOLOR_xxx (again, for
xxx=001 etc.), except for one detail. When SUMA sends a surface to
AFNI for display, it can also send a color. If that happens, then
AFNI_SUMA_LINECOLOR_xxx will have no effect. But
AFNI_SUMA_LINECOLOR_FORCE_xxx will over-ride the choice SUMA makes and
forces the color for surface number 'xxx' to be this color.

The special usage of xxx=DEF (see AFNI_SUMA_LINECOLOR_xxx) also
applies here.


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


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.


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.


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.)


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.


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


This variable controls the color of the image coordinate labels.


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.


This value of this variable is a string that is appended to the
automatically generated image slice viewer overlay label -- the
viewing of this label is controlled from the right-click popup menu
attached to the intensity bar to the right of the image itself. This
variable applies to any slice image viewer window into which the user
has not specifically set a string for this purpose from the GUI menu
item 'Label Append String'.


If this variable is YES, then the image label will be based on the
slice index rather than the spatial (mm) coordinate. This variable can
be set in the EditEnv AFNI GUI plugin (that is what 'editable' means).


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.


This numeric variable lets you set the thickness of the lines used to
draw the image viewer crosshairs. The default value is 0, which means
thin lines. The units are fractions of the image size, and the legal
range is 0 .. 0.05 (which will be very thick lines, I assure you).
This variable was introduced in March 2015 for Corianne (if there is
such a person).


Set this variable to YES to turn off crosshairs for AFNI startup.


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.


If this variable is set to YES, then the image viewer windows will
automatically re-center the cropping sub-window (if cropping is
active) around the crosshair position -- as far as possible. You can
also set this crop autocenter capability individually for each image
viewer window from the intensity bar right-click popup menu.


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
  AFNI_TLRC_BBOX_POS = distance from AC to most posterior point in box
  AFNI_TLRC_BBOX_INF = distance from AC-PC line to most inferior point
                        in box [default=55 for small box, 65 for big
  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.


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
  AFNI_ACPC_BBOX_POS = distance from AC to most posterior point in box
  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_*


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.


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".


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.


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.


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.


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.


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.


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


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.


Set this YES/NO variable to YES to output extra details when reading
DICOM images.


Set this YES/NO variable to YES to force the DICOM reading routines to
set each DICOM element based on the last occurrence, not necessarily
the first.


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,
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.


This is the time delay between frames when writing an animated GIF
file from an image viewer window. The units are 100ths of seconds
(centi-seconds!); the default value is 20 (= 5 frames per second).
Note that this value is NOT editable in the Edit Environment control
panel, so you have to set it up prior to starting AFNI (e.g., by using
an option like '-DAFNI_AGIF_DELAY=10' on the command line when
starting AFNI).


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 (the slowest) is the default.
Note that the MPEG-1 standard does NOT allow arbitrary framerates,
only these listed. To further slow down an MPEG-1 animation in AFNI,
use the AFNI_ANIM_DUP variable, described below.

AFNI_ANIM_DUP (editable)

This value sets the frame duplication factor for AGIF or MPEG
animation output. If this value 'd' is between 1 and 99, then each
frame (image) will be written out 'd' times before being incorporated
into the movie file. Note that AFNI_AGIF_DELAY can be used to slow
down an AGIF file more efficiently, but that there is no other way
(within AFNI) to slow down an MPEG file. (Some MPEG movie players
will let you slow down the animation, but that's outside of AFNI's

You can control this variable directly from the Edit Environment
control panel, or set its internal value in AFNI (or other image
viewers) from the right-click popup menu attached to the intensity
grayscale bar just to the right of the image sub-window in the viewer.
Note that the duplication factor must be greater than 1 for any
slowdown to occur. For example, if you want 6 frames per second in an
MPEG file, then a duplication factor of 4 would work (24 fps / 4 = 6

For MPEG-1 files, AFNI will set up the frame temporal encoding pattern
so that there is very little .mpg file size overhead for this frame
duplication. The same is NOT true for animated GIF files, since these
files do not have any compression along the time axis. Therefore, you
should use AFNI_AGIF_DELAY to control the frame rate of animated GIF
files, and not this frame duplication factor.


If this variable is set to YES, then when the AFNI GUI starts, a
pair of notes will be played (softly). For this to happen, it is
also necessary that
 a) the 'sox' sound software package be installed
 b) that the X11 display is local, not remote
 c) that no '-com' options are on the command line
You can also try using the 'Play startup sound' button on the
right-click popup menu attached to the logo space to the right
of the GUI 'done' button. For that button to work, conditions
a) and b) above must be true. On a Mac, you can install 'sox'
using the 'brew' package (e.g.).


The 'p' and 'P' keys in the AFNI graph viewer can be used to generate
sound from the graph data time series. However, AFNI itself does not
play sound - it uses an external player program. By default, AFNI can
use any one of these programs:
  play (part of sox) ; afplay (Mac) ; mplayer ; aplay (Linux)
and it will search your path to find one of these (in that order).
If you have some other player program you want to use, you can provide
the full path to that program in this variable, as in '/usr/bin/afplay'.


This variable is the length of the random music sequence generated by
the 'Play random music' button. The default value is 99; if you want
it to be longer, increase this value. There are about 7 notes per
seconds normally, so setting this value to 420 is about 1 minute.
Music can only be played if a sound player program is installed on
your computer, as described under AFNI_SOUND_PLAYER above.


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 expanded from time to time. Not
all features of the AFNI window setup are currently save-able this

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 filename dialog, that line
will be executed as a single command, rather than be used as a script


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


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, which can be installed on MacOS X by using the
brew package (for example).


If this variable is not set, then if the program cannot find one
of the output filter programs listed above, then a warning message
will be printed to the terminal. However, if you set this variable
to NO, then such warning messages will NOT be printed out. The
purpose of this variable is to let you silence these messages
once you get sick of seeing them.


If this variable is set to YES, then when you save an image from the
image viewer, the various steps will be printed to the terminal
as the process happens. As the variable name is implied, this
capability is here for debugging, and has not actually been used
for years (at least by the AFNI Imperial Command Team).

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:

  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:


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!).


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!


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
  "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
  "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".


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.


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', 'pink', 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.

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.


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.


This variable sets the size of the boxes that are plotted with the
1dplot '-box' option. The units are in terms of the width of the
entire plot; a value of 0.006 is the default. The largest allowed
value is 0.02 and the smallest is 0.001.


On 30 Apr 2012, a new method of rendering the 1dplot graph into an X11
window was introduced -- this method uses 'anti-aliasing' to produce
smoother lines and characters. If you want the old coarser-looking
rendering method, set this variable to YES.


When using '-noline' in 1dplot (to get a cloud of points without
lines), and when there are multiple time series being plotted with
option '-one', the normal state of affairs is that later time series
boxes get plotted on top of earlier boxes. If there are a lot of
points, then the earlier boxes get completely obscured. Setting
this variable to YES means that the boxes will be plotted in a
pseudo-random order, so that each color/shape of box has a chance
to be seen in the cloud of data.


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.


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!


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
will move the slider 1% of its height per PageUp/PageDown key or mouse


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 MIGHT be appropriate for the values in the
new dataset. [This is for Ziad!]


This variable defines the maximum value for the '**' setting underneath
the Overlay threshold slider. By default, this value is 5, but you
can change that to 4 or 6 with this variable. [This is for Phil Kohn]


This variable defines the initial power-of-ten scale for the '**'
setting. By default, this value is 1 (thresholds run from 0 to 10),
but you can change this to a value from 0 to 'TOP_EXPON'.


When thresholding a dataset with a sub-brick that is stored as shorts
(16 bit integers), the AFNI GUI uses floats, but the 3dmerge and
Clusterize functions use shorts. The difference is that the
user-supplied threshold in the latter case is rounded to the nearest
short. Thus, a threshold of 2.2 would become 2, and then a value of 2
would pass the 'greater than or equal to threshold' test -- which is
probably not what the user meant. Again, this would happen in 3dmerge
and Clusterize, but NOT in the AFNI GUI without Clusterize. This
inconsistency has been fixed, and both sets of places now threshold
using floats. However, IF you want to stick with the old method for
some grotesquely un-imaginable reason, you need to set this variable
to YES.


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,
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.


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
If you are tired of seeing these messages, set AFNI_STARTUP_WARNINGS
to NO.


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


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


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.


If this is set to 'YES', then non-commented text gets set to 0
instead of causing a read failure. The default setting is 'No'


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.


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).


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

     ni_dimen="3" >
    "1" "elvis"
    "2" "presley"
    "3" "memphis"

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.


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.


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.


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.


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.


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.


(SUBBRICK), or DSET. The GUI applies the lookup table to color the
underlay with the range determined from the slice, sub-brick or the
whole multi-sub-brick dataset,respectively, depending on this
variable. Besides the .afnirc file, the GUI allows changes from the
environment plugin menu, the right-click menu on the image viewer
colorbar or by typing Control-m in an image viewer. The Control-m
cycles among the global range types.

Previous YES/NO definitions for this variable correspond to VOLUME and
SLICE respectively and will continue to work as before. The lower
right corner of the image viewer shows the current range setting:
(2%-98%/Min2Max, Vol, Dset)

If this variable is set to YES/VOLUME/SUBBRICK, 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. Setting the variable to DSET similarly sets
the minimum and maximum based on the range of the whole dataset.

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
  [Vol]     = set from the entire volume min and max values
  [Dset]    = set from the min and max across all subbricks of a dataset
  [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.


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).


This variable controls the clipping threshold for converting atlas
regions into ROIs in the Draw Dataset plugin. The default value is 49
percent unless set by this variable as a percentage greater than 0.0
and at most 100.0 percent

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.


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).


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 NO.

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.

Note that decoding a long .mpg file that happens to be in your
directory can slow down the AFNI startup considerably!


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.


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.


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.

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:
where 'x' is 'A', 'B', 'C', etc., for the various controller labels.
(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.


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.


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.

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.


If this variable is set to NO, then the automatic color bar switching
(that was introduced by Ziad Saad) will be turned off.


If this variable is set to YES, then the 'continuous' colorscale color
bar in the AFNI GUI will have 3 panes rather than 1. The middle pane
will have the continuously variable colorscale loaded. The upper and
lower panes will have the upper and lower colors loaded, OR they can
be turned off. The sashes that controls the position and size of the
middle pane can be moved to separately set the top and bottom of the
color-ization scale (rather than make bottom = -top or bottom = 0, as
with the 1 pane color bar).

AFNI_PBAR_TICK (editable)

If this variable is set to NO, then the tick marks in the continuous
colorscale bar in the AFNI GUI will not have tick marks added on the
left and right edges. You can also set the number of tick marks this
way, if you don't want the default number (9). The maximum number
of tick marks allowed is 63, which should be enough.
* If this variable is NOT set to NO (or 0), then 9 tick marks will
  be drawn in the image window intensity bar as well (dividing it
  into 10 intervals). For this bar, the number of tick marks is
  fixed: it is either 0 or 9.


If this variable is set to YES, then the color pbar in Define Overlay
will reflect the range set by the user for the colorization process.
At some point, this feature will become the default, and then you'll
have to set this variable to NO to get the old behavior -- where the
range set by the user is shown only at the bottom right of the Define
Overlay panel, and it then multiplies the independently set top value
of the pbar to get the colorization scale. In the new method, the top
value of the pbar cannot be set by the user independently of the range
(or autorange) parameter. The intention of this change is to make the
number -> colors process somewhat more blatant. This variable's value
must be set at startup (e.g., in .afnirc), and changing it later will
have no effect. Also note that if this variable is YES, then setting
AFNI_PBAR_LOCK to YES will imply AFNI_RANGE_LOCK is YES as well.

AFNI_RANGE_LOCK (editable)

If this variable is set to YES, then the OLay range values of
different AFNI controllers that are Lock-ed together will be
coordinated. Changes in one controller will be reflected in
the others immediately.


This variable controls if changing the overlay opacity in one
image viewer window (the 1-9 arrows at the viewer right edge)
changes the opacity in all viewer windows. The default value
is YES, but you can set this to NO if you don't like it.


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.


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.


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.


This variable allows you to control the INITIAL setting of the widgets
that slave (or not) the threshold index to the overlay index. (These
widgets are on the 'Index' right-click popup chooser and on the
threshold slider right-click popup menu.)  The values you can set for
this variable, and their effects, are listed below (not case
  'OLay'    *or*  '=='  *or*  '0'  ==> threshold index = overlay index
  'OLay+1'  *or*  '+1'  *or*  '1'  ==> threshold index = overlay index + 1
  ANYTHING ELSE                    ==> threshold index is free and wild
This variable replaces the 2 variables listed below. Again, this only
controls the INITIAL setting of the widgets -- you can change them in
the AFNI GUI later at any time. Setting this variable after AFNI
starts (e.g., from plugout_drive) will have little discernable effect.


Setting this string to YES will turn on Alpha fading of the functional
overlay -- it is the same as setting the 'A' button on top of the
threshold slider to the on stated.

If Alpha is turned on, then the opacity of the overlay ranges from 1
for above-threshold pixels down to 0. Note that the alpha (opacity)
level at the pixel-wise level also is scaled by the global
opacity '1-9' control on the right side of the image viewer,
where '9' means that above-threshold pixels will be 100% opaque, and
'6' means they will be 6/9=67% opaque -- and lower opacity pixels will
be have their opacity scaled down by the same factor.

The variable-opacity overlay usually looks better (less blocky) if you
open 'Define Datamode' and set the resampling modes for the OLay and
Stat to 'Li' (linear) rather than the default 'NN' (you can also do
this via variables AFNI_resam_func and AFNI_resam_thr).

Please note that the Alpha features described above only apply if the
color scale is in the 'continuous' mode ('**'), not in the discrete
panes mode. Sorry about this, but that's the situation for the nonce.


Setting this string to YES will turn on outlining/boxing for the above
threshold pixels in a functional image overlay. The outline is done over
the pixels immediately OUTSIDE the above-threshold regions, in the
overlay image as interpolated to the underlay resolution. If the
underlay is on a coarse matrix (e.g., native EPI), these outlines
will look blocky -- you can alter the underlay display grid dimension
in 'Define Datamode' using the control 'Warp ULay on Demand', and then
alter the way the datasets are interpolated to the underlay grid using
'Resam Mode' menus. In this way, you can make blocky-looking EPI results
fictionally look as if they are beautiful and high resolution.


Defines the color used for the boxed outline of above threshold
regions, when Boxed ('B' button above threshold slided) is turned on.
See AFNI_FUNC_BOXED for more information. The default color is
black, which a few people find harsh. This variable replaces the former
AFNI_EDGIZE_COLOR, which now has no effect. Colors can be set via X11
names (e.g., "yellow", "hotpink", "#1188ff").


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.


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.


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.

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.


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



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.


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. If you set this to
0, you get the default size. If you set this to 1, no 1D files will
be read at the AFNI GUI startup.

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


Some AFNI popup messages are 'onetime' -- that is, they show up only
once for each user. This capability is there to announce changes that
should be noticed. Each onetime message is logged into a file named
.afni.recordings in the user's home directory, and if a record of such
a message is found therein, it will not be shown again. To skip
showing these messages at all, even once, set this variable to YES.


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).


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.

AFNI_EDGIZE_OVERLAY ** This variable is no longer used **

It has been replaced by AFNI_FUNC_BOXED.


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).


AFNI converts 'byte' NIFTI data types to 'short', and 'int' to
'float'. Programs that do so will issue a warning each time such a
conversion is carried out. When this variable is set to NO, as it is
now by default, each program would issue just one warning at the first
occurrence of a type conversion. Set this variable to YES if you want
to see all conversion warnings.


Use this interger variable to initialize the debug level in
plug_vol2surf. The current set of acceptable values is {0..5}.


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.


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.


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 address and local class B network 192.168.0.* addresses are
always trusted.


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).


If this is YES, then the command line logger will also echo the
command line of each AFNI program to stderr, as it starts up. This
feature is explicitly for Daniel Handwerker, and may well eventually
be considered his ultimate claim to fame in the Macrocosmic All.


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.


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.


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


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.)


By default, AFNI creates a session (internal to the program) that
contains all the input datasets -- if you input more than one session
directory, that is. This session is called 'All_Datasets' in the
'DataDir Switch' popup chooser, and should be the last session listed
in that list. If you do NOT want this session created, then set


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.


If this YES/NO variable is set to YES, then the Selenium webdriver
will be used to open a browser window in the places where AFNI uses
webpages (whereami, help,...) The AFNI_WEB_BROWSER should be set to
the browser of choice (Chrome,Firefox,Safari). The default browser
will be chrome if the AFNI_WEB_BROWSER variable is not set. If
AFNI_SELENIUM is not set or set to NO, AFNI will open the standard
browser using a system command. Selenium may be installed with "pip
install -U selenium" on a Mac or "sudo yum install selenium" on
Linux. If you need to get pip, it is available from
https://pypi.python.org/pypi/pip .


This variable should be set to the full executable path to a Web
downloader, as in
  setenv AFNI_WEB_DOWNLOADER /usr/bin/curl
If it is not set, AFNI will scan your path to see if it can find a
downloader, looking for "curl" and "wget" (in that order).


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%.


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)


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.


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


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).


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.


This integer provides an offset for the range of port numbers used by
AFNI and its ilk. This allows multiple instances of communicating
programs on one machine. Valid port offset numbers are 1024..65000.
See related options -np in afni -help. See also AFNI_PORT_BLOC.


This integer selects a bloc of port numbers to be used by
AFNI and its ilk. Much like AFNI_PORT_OFFSET, it allows multiple instances
of communicating programs on one machine. However it is easier to use.
Acceptable integer values range from 0 to a couple of thousands.
See related option -npb, -max_port_bloc in afni -help.
This environment variable takes precedence over AFNI_PORT_OFFSET.


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.


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.


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.


When you use the 'Write' buttons under 'Define Datamode' Panel, the
default is to overwrite existing datasets. However, if
AFNI_GUI_WRITE_AS_DECONFLICT is set to YES, then the decision follows
the value of AFNI_DECONFLICT

The default value for this variable is NO, which means interactive
'Write' operates in overwrite mode.


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


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.


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.


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).


If this variable is YES, then the Clusterize 'Mean' and 'Medn' Plot
graphs will have error bars plotted.


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.


This variable should be set to a number indicating the maximum number
of clusters to get a 'whereami' report when the 'WamI' button is
pressed. Since the querying the diverse atlas datasets is slow,
increasing this value much past its default value of 20 is not usually
a good plan.


As of Halloween 2018, the 'Clusterize' control panel in the AFNI GUI
uses program 3dClusterize for outputting tables and masks. One good
point of this program is that it can do bi-sided clustering, as the
GUI does. The older program 3dclust cannot do this type of clustering.
However, if for some bizarre deranged maniacal reason (e.g., testing)
you want to use 3dclust for these reporting purposes, then set this
variable to YES. Note that the internal clustering of the AFNI GUI
does not use either program - the external program is used only for
the purpose of mask saving. If you use bi-sided clustering, then
to get the saved mask have the same results as the AFNI GUI, you
should NOT set this variable to YES.


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.


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.


This YES/NO variable lets you control if the 'Histogram: Multi' plugin
plots the cumulative distribution as well as the density histogram.
Mostly this was added to subserve the nefarious conspiracies of the
dreaded Dr Cox, but if you find it useful ....


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!


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?).


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.


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.
If you set this variable to YES, 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).
  ** Formerly, this feature was on by default, but now you have **
  ** to explicitly turn it on (this is the Ziad Saad fixup).   **


'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]


If this variable is 'YES', then internal wildcard expansion (in AFNI
programs that support this capability) will NOT use the '[]' , '{}' ,
or '<>' selectors. Note that '[]' is a standard shell wildcard, so
using this variable will restrict your wildcard-ing. On the other
hand, it lets you do something like
  3dTcat -prefix ALL_rest0.nii -relabel -verb 'rest_*.nii[0]'
which will create a dataset from the #0 sub-brick of every dataset
that matches the wildcard 'rest_*.nii'.


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


Normally, AFNI checks output filenames for 'bad' characters, which are
defined as control characters and ASCII characters that will cause
trouble on the Unix command line ('*', '$', etc.). 'Bad' filenames
will not be allowed by most AFNI programs. If, for some reason, you
want to use such filenames, set this variable to YES. Don't blame
me if you get into trouble with such filenames!


If you want AFNI's InstaCorr feature to compute the FDR curve for the
on-the-fly correlation coefficient sub-brick created interactively,
then set this variable to YES. Since the FDR computations are the
slowest part of the operation, the default (if this variable is not
YES) is that FDR curves are NOT computed.


The InstaCorr controls let you use extra spatial smoothing when
selecting the seed voxel time series. By default, this extra
smoothing is a flat average over a sphere of the chosen radius:
"SeedRad". However, if this environment variable is set to YES, then
the extra smoothing is done by Gaussian blurring with the chosen FWHM:
"SeedBlur". This variable cannot be set interactively, but can be set
on the AFNI command line with the usual -DAFNI_INSTACORR_SEEDBLUR=YES


In 3dGroupInCorr's batch mode, the XYZ method of operation sets the
seed coordinates using AFNI's standard RAI (DICOM) order. If you
set this variable to YES, then the coordinates given will be
interpreted as being in LPI (AKA 'neurological') order; that is,
the given x and y values will be negated before being used inside
3dGroupInCorr to pick the seed voxel.


As of 15 June 2009, the FIR (finite implulse response) method is
applid to byte and short data. Previously, 3dmerge had used FIR only
on float data, meaning shorts and floats would be applied via Fourier
interpolation. Setting AFNI_BLUR_INTS_AS_OLD to YES will revert to
the Fourier method for such data.


Numeric value sets the size of the panning step using in the image
viewer, when you are adjusting the cropping region using the
Shift+Arrow keys on the keyboard. Defaults to 1. Legal values are
-9..9 (inclusive). Positive values means pressing Shift+LeftArrow
causes the image in the crop window to appear to move to the left;
negative values cause the crop window to move in the opposite
direction, so the visible part of the image appears to move to the
right. (Mutatis mutandum for the other directions, of course.)


This value, a number between 90 and 360 (inclusive) describes the
amount of the AJJ color circle used by the 'Colr' button in an
AFNI image viewer. If no value is given, the default is 240.
Changing this number to 360 means the color circle is continuous
from top to bottom -- an effect that is obvious if you use the 'r'
arrow buttons (on the right of the image viewer) to rotate the
color circle. The default value of 240 is purely for historical
reasons, dating back to the old FD program from Medieval Times.


This variable defines the colorscale used by the 'Colr' button
at the top right of the AFNI image viwer window to colorize
the Underlay image -- the Overlay colorization is controlled
from the colorscale on the 'Define Overlay' control pane.
At this time [Oct 2019], only the following four color scales
can be used for this purpose:
   magma  plasma  viridis  googleturbo
If you do not define AFNI_IMAGE_COLORSCALE, or you define it
to something besides one of these names (case insensitive),
then 'googleturbo' is used.
Note that the color scale can be modified somewhat by using the
'g' (gamma) arrow buttons on the right edge of the image viewer.

It is possible to change this image viewer underlay colorscale by
changing this environment variable interactively, using the driving
feature of the AFNI GUI (e.g., program plugout_drive).


This variable lets you control which keyboard modifier keys are
checked when the mouse scroll wheel is used inside the image.
If one (or more) of the selected keys is pressed while the
scroll wheel is moved, then the AFNI controller 'Define Overlay'
threshold slider moves -- otherwise (the normal case), the image
slice slider moves. The value of this variable should be contain
one or more of these strings (NOT case sensitive):
  Shift           = Shift key pressed
  Ctrl or Control = Control key pressed
  Mod1            = Alt key pressed (Linux)
  Mod2            = Command key pressed (Mac)
If you do NOT set this variable, it is like setting it to the
value 'Mod1+Mod2' (so that Alt and Command work on Linux and
Mac OS X, respectively). However, some Linux systems seem to
always have the Mod2 mask set for the scroll wheel, and so
the wheel ALWAYS change the threshold slider and not the slice.
To prevent this sad thing from happening, set this variable to
just 'Mod1'. Furthermore, if you include the string 'Debug'
in this variable, when the scroll wheel is used over the image
sub-window, some information will be printed out about what the
program detects, which might help you set things up correctly.
On my Mac, I get the following output when using the scroll wheel
twice -- once with no key pressed and once with the Command key:
  ++ Scrollwheel (imag): button=5 ; state mask=0x
   +   (mask: shift=1x ctrl=4x mod1=8x mod2=10x mod3=20x mod4=40x mod5=80x)
   +   change slice
  ++ Scrollwheel (imag): button=5 ; state mask=10x
   +   (mask: shift=1x ctrl=4x mod1=8x mod2=10x mod3=20x mod4=40x mod5=80x)
   +   change threshold
The second use shows that the 'state mask' (which shows the modifier
keys) was hexadecimal '10x', which corresponds to the 'mod2' value.


The old 'frivolous' AFNI dummy dataset was replaced with a
low-resolution edition of the N27 dataset on 12 Feb 2010. If for some
absurd reason you want the old dummy dataset back, then set this
variable to OLD. (Recall that the dummy dataset is only created if
you start the AFNI GUI without any input datasets at all -- AFNI is so
constructed that it needs SOME dataset present to be able to operate:
hence, the dummy dataset concept.)


When AFNI programs print out informative (and fun) messages about the
size of files, memory space, etc., by default commas are inserted,
as in "8,765,432". If you want these numbers printed as "8765432"
(for whatever hideous and twisted reason), set this variable to YES.


If this variable is set (where 'x' is A, B, C, ...), then for AFNI
controller 'x', whenever the crosshair viewpoint changes, the DICOM
order (x,y,z) coordinates and the dataset 3D index (i,j,k) will be
written to the file whose name is given by the value of this variable.
As a special case, if the filename is 'stdout', then the coordinates
are written to standard output. A sample command

  afni -DAFNI_FILE_COORDS_A=stdout

If the file already exists when afni starts, it will be over-written;
that is, it is opened in "w" mode.

This feature may be referred to as the Jen Evans special.

AFNI_AUTORANGE_POWER – this variable is now obsolete

If this variable is set to a value between 0 and 1 (exclusive),
then the functional overlay 'autoRange' value will be set to
the largest value in the dataset raised to this power. By default,
the autoRange value is computed as if this power is 1.

AFNI_AUTORANGE_PERC - experimental at this moment

If this variable is set to a value P between 2 and 99 (inclusive),
then it indicates that the functional overlay 'autoRange' value
will be set the P-th percentile point on the cumulative histogram
of the absolute values of the nonzero entries in the Overlay
dataset sub-brick being viewed. To be less confusing, if P=95
(for example), then the nonzero absolute values are tabulated
into histogram bins from smallest (percentile=0) to largest
(percentile=100), and the value at the 95th percentile will
be chosen -- so that only 5 percent of the values in the
dataset are larger than this autoRange value. The reason for
doing this is to avoid allowing a few large values to distort
the overlay color scale.


This variable, if set, allows you to specify the set of colors used
for the FIM Ideal overlay in the graph viewer window. Separate color
names by colons, as in "red:green:blue". The first column in the
Ideal 1D file gets the first color; the second column gets the second
color, and so on. The variable AFNI_ORT_COLORS can similarly be used
to specify the colors for the FIM Ort overlay.


If this variable is set to NO, then the 'AFNI Tips' button will not
use the HTML window to display the requested information -- a plain
text window will be used. You should only need to use this variable
if the AFNI Tips window crashes on your system.


If this variable is set to YES, then font-changing HTML tags will be
deleted before opening the 'AFNI Tips' HTML window. Try this first
to avoid crashes, before using the previous variable to turn off the
HTML tips entirely.


The function fgets() is the Unix standard for reading text lines from
a file. However, it assumes that the text file lines end in the Unix
standard end-of-line character (ASCII 0xA). Files created on
Microsoft platforms use a different end-of-line character (ASCII 0xD).
The result is that Microsoft-ized text files don't work well with
fgets(). AFNI uses its own function, cleverly called afni_fgets(), to
read text lines, to avoid this problem. However, this function is 4-5
times slower than the system fgets() function, so if speed if crucial
-- as when reading a giant 1D file -- then set AFNI_USE_FGETS to YES
to make AFNI programs use the system fgets() function. The best way
to do this would be on the command line, as in the simple example
  1dcat -DAFNI_USE_FGETS=YES bigfileA.1D bigfileB.1D > bigfileAB.1D
In such an example, you won't see a 4-5 times speedup, since actually
most of the time is spent decoding the text in the file into numbers
and then writing them back out -- you'll probably see a speedup of
about 1.2-1.4 instead -- not trivial, but not exhilarating.


These variables affect the way the '3dAllineate -final wsinc5' windowed
since interpolation option works. See the output of the command
  3dAllineate -HELP
for the details. You can control the width of the sinc window, the
tapering function, and a couple of other useless options.
** N.B.: You can turn off the message that the wsinc5 code prints out
detailing the parameter setup by setting AFNI_WSINC5_SILENT to YES.


The default '-final' option for 3dAllineate is 'cubic'. You can change
this default to any other legitimate value, such as 'wsinc5' or 'NN'.
This variable is provided to allow you to force the final interpolation
mode into a script that doesn't allow any easy way to affect it, such
as that generated by afni_proc.py.


This numeric variable (between 1 and 9, inclusive) sets the step size
used when you press the up/down arrows on the 'Index' control in the
left column of the main AFNI controller. Setting this value to 2 (say)
let's you scroll through an image time series seeing alternate time
points. This feature can be useful when looking at datasets where
sub-bricks alternate in type -- for example, from 3dttest++, where the
even-numbered volumes are effect size estimates, and the odd-numbered
volumes are the corresponding t-statistics. (This value can also be
set interactively from a popup chooser activated by right-clicking
on the 'Index' label to the left of the up/down arrows.)


The ScatterPlot plugin lets you graph the data in one sub-brick along
the x-axis and the data in another sub-brick along the y-axis. It also
computes some straight line y=ax+b fits to the graph. By default, it
does 2 different fits, with least sum of squares (L2) and least sum
of absolutes (L1) criteria. The L2 line is plotted in red (and thus
corresponds to the Pearson R also shown in red), and the L1 line is
plotted in blue (and corresponds to the Spearman rho shown in blue).
With this variable, you can turn off the plotting of either or both
of these lines, which are often very nearly the same. If the value
of this variable contains the string 'NOL1', then the L1 line won't
be shown, and if the value of this variable contains 'NOL2', then
the L2 line won't be shown. Thus, if the value of this variable is
'NOL1+NOL2', neither line will be plotted.


This variable lets you choose the size of the boxes plotted in the
ScatterPlot plugin. The units are fractions of the plot width,
so the reasonable range for this value is 0.0 to 0.01 (not inclusive).
If this variable is not set, or the value is outside of this range,
then the size of the boxes is set based on the number of points
being plotted. The only reason for using this variable is if you
wish to create a sequence of scatterplots and ensure that the points
plotted in different graphs have a uniform size of boxes.


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.


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.)


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.


If this variable is set to YES, dataset names with spaces in them will
go through "normal" reading routines, rather than using
THD_open_tcat() to try to combine multiple datasets.


If set to YES, then the AFNI GUI 'Jump to (xyz)' behavior is altered to
move the crosshairs to the chosen location incrementally, rather than
in one big jump. The reasons for using this feature are (a) to help
get a feel for the transit, and (b) just plain fun.


The value of this variable will alter the 'username@machine' listing
in the history notes generated by AFNI programs. If this variable
is NOT set, then your user login name and machine ID are put in the
header; otherwise, the value of this string is used. You can set this
string to the null string '' if you wish to hide your identity totally.


If this variable is set to YES, output datasets will have a
HISTORY_NOTE which can be seen via 3dinfo, for example. If set to NO,
output datasets will not have any HISTORY. This is one method for
making datasets anonymous.


These variables control the setting of the 'global' and 'local' ETAC
calculations, and are equivalent to using the '-ETAC_global' and
'-ETAC_local' command line switches to 3dttest++. If you set a
variable to YES, then that commands the relevant ETAC thresholds
to be calculated; if you set a variable to NO, it turns off the
relevant calculation. If you do not set a variable, and you do
not use the 3dttest++ command line option, you will get whatever
the default ETAC method(s) are enabled.

| 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       |
| Alpha Quadrant, Milky Way Galaxy          |
| Local Group, Virgo Supercluster           |


If you do NOT want to see the 'linkRbrain' button in the Clusterize
GUI, then set this variable to NO.


This variable sets the name of the linkRbrain server to use. The default
server is 'linkrbrain.eu'.

2.5.5. Vars for realtime functionality


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_Resampling   = "Cubic", "Quintic", "Heptic", "Fourier",
                             or "Hept+Four"
AFNI_REALTIME_Reg_Base_Mode= "Current_Run", "Current_Run_Keep", or
AFNI_REALTIME_Base_Image   = an integer from 0 to 9999
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

AFNI_REALTIME_External_Dataset = name of dataset to use as external
                                 basis for registration
        * if this variable is set, then the plugin assumes that
          AFNI_REALTIME_Reg_Base_Mode is "External_Dataset"
        * but AFNI_REALTIME_Base_Image is ignored
        * instead, you can use a sub-brick selector here, if desired;
          for example: setenv AFNI_REALTIME_External_Dataset 'X+orig[3]'
        * to be brutally clear, you can give the name of a dataset that is
          NOT in the current directory -- unlike when using the plugin GUI
        * the plugin GUI will NOT show the choice of external dataset given
          via this environment variable!

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_Mask_Dset  = String (the name of a dataset)

        This option allows the user to set the Mask dataset, used to
        send ROI and motion data to a program listening at a socket.
        This environment variable overrides the variable set in the
        plugin interface, allowing it to change per run.

        Set the variable to None to either clear the mask or to allow
        the interface mask to apply. Note that this can be done via a
        drive afni command, allowing changes after afni is already
        running, e.g. plugout_drive -com 'SETENV
        AFNI_REALTIME_MASK_DSET None' -quit

        This variable controls writing individual volumes as they are acquired
        by the realtime plugin. Valid Numbers and their effects are:
            0 = Off        : do nothing [default]
            1 = Acquired   : write each volume as it is acquired
            2 = Registered : write each registered volume
            3 = Merged     : write each merged volume (merged across channels)

N.B.: 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_reset_output_index = YES/NO

        By default, output files will be named with a prefix,
        PREFIX__NNN, where PREFIX is given by the AFNI_REALTIME_Root
        variable or the Root in the interface, and where NNN
        increments per run.

        If this variable is set to YES, then the plugin will try to
        use NNN=001 each run.

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.


        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.


        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.


        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.


        If set, this is the maximum number of controllers that AFNI will
         open for multi-channel acquisition display. If more channels
         than this are sent, only the first ones will be displayed.
     ** If this variable is not set, its value defaults to 2.


        If set, this variable controls the initial setting of the
        "DataWriting" control, where 0=Off, 1=Acquired, etc. If not
        set, the default value is 0.


        If set, this variable controls the initial setting of the
        "ChannelMerge" control, where 0=none, 1=sum, 2=L1 norm, 3=L2norm.
        If not set, the default value is 0.


        If set, this variable controls the ChannelMerge registration mode.
        Here: 0=none            : no merge registration
              1=reg_merge       : register merged dastaset
              2=reg_chan        : apply merge xform to all channels
        The default is 0.


        If set, this variable specifies a list of 0-based channels to
        merge, rather than using all channels. The format is akin to
        sub-brick selection. For example '0..$' means all and
        '0,5..7' means 0,5,6,7.

For detailed 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".
Also see program rtfeedme.c and "rtfeedme -help".

2.5.6. Vars specific to NIML I/O


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.


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.


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.


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


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.


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.

2.5.7. Vars for 3dDeconvolve


3dDeconvolve and 3dREMLfit create statistics datasets that have sub-brick
labels of the form 'NAME#0_Coef', where 'NAME' is the task name set up
when running the program. This environment variable lets you replace
'#' character with another character; for example (in tcsh):
which will create labels of the form 'NAME_0_Coef' instead. The single
character value you supply must be a printable character - not a space,
not a control character, and not the '~' character (which is special).

Please note that in the future, the default '#' may be replaced by
some other character in the AFNI setup. When that happens, datasets
created after that date will not be exactly compatible (as far as
the sub-brick labels) with datasets created earlier. The purpose of this
environment variable is to allow you to make these programs backward
compatible, if necessary. [11 Jul 2019]


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.


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.


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.


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


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.


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.


Normally, when you use the -stim_times_AM2 option, the regression
against the covariates is 'centered' around the mean of the values
given. If you want the regression to proceed directly with the
covariate values as given, set this option to YES. Please do NOT do
this unless you understand what this means!!!


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.


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
  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.)


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.


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.


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


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.)


If this variable is set to YES, then the adjustment of FDR q-values
downwards by allowing for the estimate of the number of true
negatives (e.g., as discussed by Storey, Benjamini, and others)
will NOT be carried out. As of 26 Mar 2009, this adjustment of
q-values is the default in AFNI programs. If you want the old
behavior, set this variable to YES.


If this variable is set to YES, then the FDR calculation is made using
the non-independent assumption, as in the '-cdep' option for program
3dFDR. This setting will affect the calculation of FDR curves via
program 3drefit, et cetera.


If you want 3dDeconvolve to check the input dataset time series for
initial saturation transients (a somewhat time consuming process),
set this variable to NO. You can also use program 3dSatCheck for
this purpose. Or just look at your data (please!).

2.5.8. ATLAS and WHEREAMI env variables


These variables control how AFNI and whereami make use of various atlases and template spaces. The variables may also affect how other AFNI programs use atlases as input datasets.


This list contains the names of the atlases that should be queried
when no specific atlas has been requested. For example, the afni GUI
and whereami, by default, do not load all the atlases specified in the
AFNI_atlas_spaces.niml file. If this variable is not set, the
TT_Daemon atlas and the cytoarchitectonic Eickhoff-Zilles in MNI_ANAT
space are loaded. If the variable is set to a list like
"TT_Daemon,DD_Desai_PM", then only these two atlases are loaded. The
list of atlas names may be separated by commas or semicolons. A
special case of "ALL" may be set, and all the available atlases will
be loaded.


This list contains the names of the template spaces that are shown
when whereami reports the coordinates among various spaces. By
default, the list contains "TLRC,MNI,MNI_ANAT". As with
AFNI_ATLAS_LIST, this list may also be set to "ALL".


This variable sets which atlas to use in the AFNI GUI for "Atlas
Colors", "Go to Atlas location", "Draw Dataset" and "Renderer"


This variable sets which space to use in the AFNI GUI for "Jump to
(spacename)" function where this would default to "MNI". Choose a
valid spacename from the current list of spaces in "whereami
-show_spaces". The jump function transforms the user input coordinates
from that space to the space of the dataset.


This variable sets which directory or directories to search for AFNI
atlas datasets that have been defined in the AFNI_atlas_spaces.niml or
CustomAtlases.niml file. For all afni programs and scripts that use
atlas and template datasets, the program will preferentially use (in
order) the file path included in the dataset filename definition, the
AFNI_ATLAS_PATH, the AFNI_PLUGINPATH or the standard PATH values.


Described above, this variable is used for several purposes. For
whereami, this variable sets the directory to load atlases and NIML
files if not in the current directory. If this variable does not exist
or the referred file does not exist, then the atlas is searched in the
user's current PATH setting. If this is set, atlases will be found
more quickly than searching all the directories of the entire
PATH. Searches of the PATH variable for whereami usage stop at the
first occurrence of the searched file, so placing the AFNI directory
earlier in the PATH will dramatically increase the speed that the file
is found.


Sets precision for whereami output. Higher field data and animal
atlases require higher precision. The default value used for focus
point among template spaces is still 0 decimal places (closest mm),
but animal data requires three decimal places. Value may range from 0
to 10.


This variable controls the output of detailed messages about various
tasks involved in loading atlases, transformations and composing query
results. By default, this information is not shown. This integer sets
the debugging level in whereami routines. Currently used values range
from 0 to 3.


This variable may also specify the default location of AFNI atlases. This
variable is maintained mostly for backward compatibility. By default, this
is not set.


Turns off warnings about various whereami features - like queries that
have reached their limit of returned results. By default, warnings are
displayed only the first time a particular message is encountered.


By default, only the first nine structures are displayed within a
particular atlas. You may increase or decrease this to show more or
fewer structures in the whereami results.


By default, whereami searches a radius of 7.5 mm. Set a radius up to
9.5 mm.


Minimum probability AFNI considers in probabilistic atlases


The default template space is assumed to be TLRC. This is used for
coordinate input to whereami, the whereami GUI and for TLRC view
datasets without a template space explicitly set in the dataset


The default view extension used for output when creating AFNI format
datasets from NIFTI datasets.This variable is only applicable for
sform and qform codes that do not have clearly defined views
(sform/qform code = 2). Set to "tlrc" or "orig". See also
can be used for spaces other than MNI or TLRC including MNI_ANAT or D99


Sets preference for NIFTI files to use sform or qform codes and
matrices to determine space, origin and orientation. Set to 'S' or 'Q'
for sform or qform respectively. If not set, NIFTI files are read
using the non-zero form code or the sform code if both are set.


These variables allow the addition of more atlas definitions to the
global list of atlases, templates, spaces and transformations. The
variable should be set to the name of a NIML file with the same format
of the AFNI_atlas_spaces.niml file. These can be customized by site
(supplemental) or by subject (local) and follow the same search order
as the AFNI_atlas_spaces.niml file. In order to be included in default
searches, additional atlases or template spaces would also need to be
unless those are set to "ALL".


Allows the addition of atlas definitions to the global list of
atlases, templates,spaces and transformations. The variable should be
set to the name of a directory that contains a SessionAtlases.niml
file with the same format as the AFNI_atlas_spaces.niml file. Also see


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.)


If this variable is not set, the default font size is used in the
'Where am I?'  popup window.
If this variable is set to 'BIG', then a larger font size is used.


Atlas region labels can be shown as either as a short name or with a
longer, more descriptive name. Note that most atlases have only the
short name available. The whereami GUI and command line can show either
or both labels with this variable set to "longname", "both" or "name",
where "name" is only the short, standard version. The overlay panel
and image viewers can show this label too. The names are separated by
a vertical pipe symbol if both are in the atlas header.
The default is to show both names if they are available.


When set to YES, the Where Am I GUI becomes 'web-enabled', i.e. the
report becomes clickable to open web pages from the output. Most
features are still experimental. See AFNI_NEUROSYNTH and AFNI_SUMSDB
below for examples. The default value is 'NO'.


When set to YES, provides link for MNI coordinate in Where Am I GUI to
the Neurosynth site. Requires AFNI_WEBBY_WAMI to also be set to
YES. The default value is 'NO'.


When set to YES, provides link for MNI coordinate in Where Am I GUI to
the SumsDB site. Requires AFNI_WEBBY_WAMI to also be set to YES. The
default value is 'NO'.

2.5.9. Interacting with other progs and miscellany


If this variable is set, do NOT make suggestions if a program parsing
error is encountered.


Set this variable to your favorite GUI text editor.


Set this variable to your favorite image viewer.


Set this variable to your favorite pdf viewer.


If set to YES, allow approximate searching functions to log their
behavior in a file named ~/.afni/help/aps.log.txt


If set to a non-empty string, an attribute called HISTDB_SCRIPT is
added to the header of AFNI datasets at write time. The value of the
attribute is that of the variable AFNI_HISTDB_SCRIPT.
At the moment, this variable is solely for Tom Ross's nefarious
history databasing schemes.


If set to YES, enable distance measures that are not ready for prime
time in the instacorr interface.