12.3.3. General options for AFNI programs

Overview and note on default settings

The following is a description of some generally applicable options when running AFNI programs. Each should be applicable in most AFNI program.

As part of the default AFNI setup, you (are supposed to) generate the file of default environment variables (envs) for AFNI. This file is called ~/.afnirc, meaning that it lives in your home directory, and is “hidden” in the sense that it is not shown with a default ls (because of the . at the start of its name). See if \ls -a ~/.afnirc shows the name of a file for you. If not, run afni_system_check.py -check_all, and follow the copy+paste instruction at the bottom to generate the default one.

The page listing all AFNI environment variables and their descriptions is here: AFNI environment variables.

Whenever you run an AFNI program, the ~/.afnirc file of environment variables gets sourced. So, if you want to change behavior of something in a semi-static way, set the environment variable there.

You can also set environment variables in scripts you write. This is a more “task-specific” way of setting behavior.

The first section here will show you how to set an env via an option for that command. This setting only has effect for the duration of that command’s execution.

Environment variables per-command: -Dname=val

You can set an environment variable to be used just for a particular program call by adding an option with the syntax -Dname=val, where ‘name’ is an environment variable, and ‘val’ is the value you want it to take.

For example, the following sets the line width to a desired value and green color (ignoring whatever the default in ~/.afnirc is):

1dplot                                 \
    -DAFNI_1DPLOT_COLOR_01=rgbi:0/1/0  \
    -DAFNI_1DPLOT_THIK=.04             \
    '1D: 3 4 5 3 2 1'

This is quite general. You can use this with the AFNI gui, say afni -Dname=val, etc. Enjoy the freedom!

Checking environment variable settings: afni -Vname=

As noted above, you should have default environment variables set. And hopefully you have altered them to your heart’s content.

To find out what an environment variable is set to, you could open up the ~/.afnirc file. But you might change things in a script or just hate opening text files. To find out the current value of an environment variable name from the command line, you can run the main afni program with the following option specification:

afni -Vname=

Yes, the actual variable name needs to be sandwiched between V and =. So, for example, to check out the default thickness of lines drawn in the 1dplot-style windows, you could run:

afni -VAFNI_1DPLOT_THIK=

There might be some other text displayed at the same time, so you might turn on quiet mode and the -no_detach option for just getting the specific output:

afni -q -no_detach -VAFNI_1DPLOT_THIK=

Overwriting: -overwrite

Most AFNI programs will not destroy existing datasets. Including this option tells them that it is OK to write over an existing dataset file if necessary.

For example:

3dcalc                        \
    -a DSET                   \
    -expr 'a**2'              \
    -prefix OUTPUT            \
    -overwrite

... will write OUTPUT whether there was a pre-existing dset there or not.

Ignore the default env vars: -skip_afnirc

Including this option leads to skipping the processing of your ~/.afnirc file. That file, if present, is be used to set environment variables to affect AFNI programs; so, this basically ignores any of those defaults.

Consider this:

1dplot                                 \
    -skip_afnirc                       \
    '1D: 3 4 5 3 2 1'

... which would skip any color/line thickness/etc. settings in your ~/.afnirc file.

Sometimes you might want to run an AFNI program and not have your settings applied; this option provides an easy way to skip such settings.

Program help: -hview (and other opts)

If you type the name of an AFNI program in the terminal and hit Enter (with no options), the help should be displayed in the terminal.

Similarly, most programs also have the simple option -help or -h to display the help in the terminal (a few programs actually require such an explicit plea for help).

If you want, you can redirect the help into a file, such as with:

1dplot > file1.txt

1dplot -help > file2.txt

You can then open it in a text editor, or email it as a special Valentine’s Day card.

My favorite way to view the help, though, is to have it open in a text editor directly, using the -hview option:

1dplot -hview

Your text editor automatically moves the background, too, so you can keep typing. You can set the text editor being used with the AFNI_GUI_EDITOR environment variable (e.g., in your ~/.afnirc file). For example, I have the following line in my settings file:

AFNI_GUI_EDITOR = /usr/bin/emacs

Yaaaaaay, emacs! But whatever you choose is up to you (default on Linux is probably gedit; whooooo knows what Mac chooses?).