AFNI Cheat Sheet
Document Actions
It's probably best to be running AFNI while you read this, so you can try things out.
Hidden Popup Menus
If you look carefully at the mouse cursor in AFNI, it changes shape when it is over a region that has a hidden right-click popup menu. The "yes popup" cursor is more vertical and has a yellow body. The "no popup" cursor is more horizontal and has an orange-y body. The image below (hopefully) shows the two different conditions: the snapshot to the left shows the "yes popup" cursor (near the word "DICOM") and the snapshot to the right shows the "no popup" cursor (near the "X").
Unfortunately, on some window managers (e.g., Gnome), the system doesn't let the program change the cursor. As a result, this visual hint isn't universally available.
Of particular note, perhaps, is the popup menu attached to the large blank square just to the right of the "done" button. Some other popup menus are at
- The coordinate table in the upper left of the AFNI controller window.
- The 'Inten' label atop the color pbar in the 'Define Overlay' control panel.
- The color pbar itself, when in 'continuous colorscale' mode.
- The image sub-window in an image viewer.
- The intensity bar in an image viewer.
- The sub-graphs in a graph viewer (not really a menu: just gives some statistics for the time series in that voxel).
- In the 'Render [new]' plugin: on the 'See Xhairs' button, and on the 'Color' label in the 'Overlay' control panel.
Background Images
You can see some color image peeking through in the background of the above AFNI controller snapshots. This image is chosen in my ~/.afnirc file by setting an environment variable to the full filename of an image:
AFNI_LOGO16_IMAGE_A = /Users/rwcox/Pictures/background/titicaca_1.jpgThis sets the background for controller #A (the main controller and the image windows). Purely for fun.
Keyboard Shortcuts in an Image Viewer
When the mouse cursor is in the image sub-window itself, several keys will
do semi-useful things:
- Arrow keys = move the crosshairs one voxel in the indicated direction.
- PageUp and PageDown = move one slice up or down (i.e., like moving the slider below the image)
- Delete = when using the "Draw Dataset" (ROI drawing) plugin, this is equivalent to pressing "Undo"
- F2 = when using "Draw Dataset", is equivalent to toggling the "pen" mode in the image viewer on or off
- q or Q = close the viewer window (i.e., "Done" button)
- v or V = "Video" mode:
- advance the slice selection continuously
- upwards for 'v', downwards for 'V'
- when the end of the slice count is reached, the slider wraps around to the other end
- the time between frame advances is given by environment variable AFNI_VIDEO_DELAY, which can be set from the "Edit Environment" controls
- Pressing the space bar (while the cursor is in the image sub-window) will stop the video image progression.
- r or R = "Ricochet Video" mode:
- like "Video" mode above, but when the end of the slice count is reached, the direction of slice advance reverses
- > or < = move one slice up or down, like PageUp and PageDown (this is copied from the graph viewer)
- z or Z = zoom out or in (like the "z" down and up arrows)
- p or P = toggle "pan" mode on or off (like the "pan" button)
- i or I = decrease or increase the image fraction (like the "i" down and up arrows)
Keyboard Shortcuts in a Graph Viewer
The AFNI 3D+time graph viewer has a number of keyboard shortcuts, as well.
Some of them correspond to "Opt" menu items; on the menus, these are flagged
in square brackets, as in "[a]".
- Right and Left Arrow keys = move forward or backward one point in time
- PageUp and PageDown = move one slice forward or back
- Z and z = move one slice forward or back
- N = lets you set the number of sub-graphs directly by typing into the
graph window:
- Press the N key
- Type some number (e.g., the characters 11)
- Press the Enter (or Return) key
- Et viola! The number of sub-graphs changes
- m and M = decrease or increase the number of sub-graphs by 1
- a = auto-scale the graphs to fit pleasingly into the windows
- - and + = adjust the scale of the graphs down and up
- g and G = adjust the spacing of the vertical grid lines down and up
- q and Q = quit the graph viewer
- b = cycle between the different baseline options
- The baseline mode is indicated after the word "Base:" at the bottom of the viewer window.
- In all modes, the vertical scale of each sub-graph is the same; that is, they all have the same factor for conversion of changes in data values to changes in vertical pixels on the screen.
- The modes differ in how the value at the bottom of the sub-graph
is determined (the "baseline" value):
- separate mode = each sub-graph's baseline value is the minimum value that occurs in that individual time series
- common mode = the minimum value that occurs in all the currently visible sub-graph time series is the baseline value
- global mode = the baseline value is set by the menu item Opt→Baseline→Set Global (default setting is smallest value in entire dataset)
- The animated image below cycles through the 3 modes, alternately using the 'b' key to change mode and the 'a' key to rescale the graphs to look good.
(Individual images saved with 'S', then padded with 'pnmpad -bottom=94', then edited with 'gimp' to add text, then assembled into animated GIF with 'ppmtogif' and 'whirlgif').
- The baseline value for the central sub-graph is shown at the lower left corner of the graph array (just above the AFNI logo).
- At the upper left corner is the value at the top of the
central sub-graph sub-window, and (in brackets) the range
of values represented by the height of one sub-graph sub-window.
- These displays follow the old 'FD' program, the ur-AFNI. For more information on the relation between FD and AFNI, see this entry
- After switching baseline modes, it is often necessary to auto-scale (via 'a') to make the graphs look decent.
- h = show a horizontal dashed line at the level y=0
- t = switch in and out of text mode (shows numbers instead of curves)
- S = save the graph window to a PNM image file
- L = hide/show the AFNI logo in the lower left corner of the window
- v and V = "Video" mode, through time
- r and R = "Ricochet video" mode, through time
- w = write data from central time series graph to disk in a .1D file
Features of Define Overlay
The threshold slider and color 'pbar' have a few obscure features:
- Pressing Up or Down keyboard arrow while the cursor is in the threshold slider will cause the threshold to change by 1 in the 4th place. PageUp and PageDown cause it to change in steps of 10. These can be useful for precise adjustments.
- In the 'continuous' color pbar, left-clicking in the pbar causes the color map to flip end-for-end. Right-clicking pops up a menu that lets you choose a new color map.
- The 'Inten' label above the color pbar has a right-click popup menu.
- The 'Rota' buttons rotate the color pbar up and down. This can be useful for making fun movies, especially with SUMA.
Lock-ing Controllers Together
The New button lets you open a new AFNI main controller window. In turn, you can use that to Switch to view different datasets. In this way, you can look at multiple brain volumes side-by-side on the screen. Each controller gets a letter label, starting with A; this label is shown in the controller's titlebar.
The Define Datamode→Lock menu lets you "lock" different AFNI controllers together. In this context, "Lock" means that the crosshair coordinates will be the same. Image and graph viewers from the same AFNI controller are always locked -- that is, when you click in one viewer, the others jump to match. By default, viewers started from different controllers are not locked together.
By setting the environment variable AFNI_ALWAYS_LOCK to YES (e.g., in your .afnirc file), you can force all controllers to be locked together from AFNI's startup. This is what I do, for example.
It is important to realize that there is only one lock, and a controller is either in the lock or not in the lock. That is, you cannot lock controllers A and B together, and then lock C and D together separately.
The Lock menu also lets you "Time Lock" controllers together. This means that if the datasets being viewed have a time-axis, then switching the time index being viewed (via the Index chooser, or in a graph viewer) in one controller will affect the time index in the other controllers.
Another option is "IJK Lock". This says to lock viewers together based on the spatial indexes in the 3D volumes, rather than the spatial coordinates. This feature is fairly specialized, and is hardly ever useful.
When you open a new controller that is participating in the lock, its viewers will not automatically jump to the lock position. You have to do something to force this jump. The simplest thing to do is to click in some viewer, which will make all the other locked viewers jump to match. The other way is to use the Lock→Enforce button, which will force all the locked viewers to jump to the coordinates corresponding to the given controller.
Also available on the "Edit Environment" control panel are three variables that let you lock the threshold and color 'pbar' sliders together between different AFNI controllers.
- Edit Environment can be accessed from the Datamode→Misc menu, and various hidden popup menus.
- AFNI_THRESH_LOCK lets you lock the threshold sliders together, so that as one controller's threshold is changed, the others also change. This lock can be enforced through the actual threshold value, or through the nominal p-value of the threshold.
- AFNI_PBAR_LOCK locks the color pbars together, so that if you change the color mapping in one controller, the others will follow.
- AFNI_RANGE_LOCK locks the dataset value-to-color 'ranges' together (the range number is either set via the autoRange toggle, or via the numerical chooser just below it).
- At this time, the corresponding controls in the AFNI volume rendering plugin do not participate in these locks. Sorry about that.
Image Viewer 'Intensity Bar'
The vertical bar to the right of the image in an image viewer is called the
"intensity bar"; it shows the range of grayscale values that are mapped from
the numbers in the image. If you have "Hints" enabled on the Datamode→Misc
menu, then the popup hint for the intensity bar is the numerical range that is mapped
to the grayscales shown.
There are three ways that AFNI can compute the numerical range for displaying an underlay image (except for RGB underlays, which are not interpreted through the intensity bar): These methods are:
- 2%-to-98%:
For each slice shown (independently), the histogram of the numerical values is built. The value at the 2% level is set to the bottom of the intensity bar, and the value at the 98% level is set to the top of the intensity bar. The intention is not to let a few very small or very large values dominate the display. This method works well on "natural" images, but is confusing on synthetic or simulated data, which might consist mostly of extreme values. - Min-to-Max:
For each slice (independently), the smallest number maps to the bottom of the intensity bar and the largest number to the top. - Fixed Display Range:
In this method, the user chooses the numbers for the bottom and top of the intensity bar. This is the only way to make sure that each slice from a volume will be displayed the same way.
The third method can only be selected from the right-click popup menu attached to the intensity bar. The Choose Display Range item opens a small chooser window labeled
Display range: bot top [ztop]In this small window, you type two (or three) numbers separated by blanks. The first value is the intensity bar's bottom; the second value is the intensity bar's top. After you do this and then press Set or Apply, the images displayed in this viewer with use this fixed display range. To turn the fixed display range mode off, you must enter "0 0" into the Display range control window.
The optional third value [ztop], if entered as the number 1, indicates that values above the intensity bar's top are to be set to 0. This is occasionally useful; at least, I had a motive for including it on some occasion.
Adjusting the Intensity Bar Itself:
You can adjust the gradation of grayscale values along the intensity bar in
several ways. Some of the buttons along the right edge of the image viewer
are for this purpose:
c = Contrast up or down
b = Brightness up or down
r = Rotate the bar up or down
g = Modify the 'gamma' factor
If you also set environment variable AFNI_STROKE_AUTOPLOT to YES, then as you drag around changing the intensity bar's mapping, you will also get a popup window that shows the histogram of the current slice and the changing curve that maps numerical values to brightness. This plot can be handy when you are trying to get a particular numerical value in the image to display well.
(This click-and-drag method of adjusting the grayscale mapping is apparently common on radiological workstations. I was convinced to put this into AFNI by John Butman, a radiologist at the NIH. I thought it was weird at first, but I quickly got used to it and don't bother with the right-side buttons much any more.)
