5.2. List of all AFNI GUI tips and keyboard shortcuts

5.2.1. Overview

There are typically (at least) four ways of controlling behavior in the AFNI GUI:

• clicking a button or menu item

• using a keypress (i.e., keyboard shortcut)

• providing command line options for the GUI to use as it opens (referred to as driving AFNI).

• setting an environment variable (such as in your ~/.afnirc file)

And in some cases, left- and right-clicks do different things, as well! Note that the SUMA GUI has the same trio of controllability options.

Here we list many of useful GUI features, mainly focusing on clicking and keypresses; once you know these, you are actually a good ways into being able to drive AFNI well, too.

We might/should add more over time.

5.2.2. AFNI For Absolute Beginners

To use AFNI, you must have some data stored in a format that the program understands.

(a) The major formats for which AFNI is programmed are:
    ++ AFNI formatted datasets, in .HEAD and .BRIK pairs of files;
    ++ NIfTI-1 formatted datasets, in .nii or .nii.gz files.

(b) When you start AFNI, any datasets in the current directory will be ready
    for viewing.  If there are no datasets to read, AFNI will pop up a
    message.  At this point, you can do one of 2 things:
    ++ Quit AFNI, change directory ('cd') to a directory with some datasets,
       and restart the program (this is what I always do); or,
    ++ Use the 'DataDir Read' button in the second column of the main AFNI
       controller to navigate to a directory with some datasets.
    When there is no data, AFNI creates a 'dummy' dataset for you to look at,
    if you want to play with the image viewers.

(c) To open an image viewer, click on one of the 'Image' buttons in the left
    column of the main AFNI controller.
    ++ Left-click in the image to move the crosshairs around.
    ++ Click or click-drag in the slider below the image to change slice.
    ++ The controls to the right of the image let you adjust the image
       contrast, brightness, zoom factor, etc.
    ++ The controls to the bottom of the image let you carry out various
       operations on the image, such as saving to JPEG format, and making
       a montage (array) of slice images.

(d) If a dataset has more than one 3D volume in it (usually that means it
    has a time axis, like an FMRI EPI dataset), then you can use the 'Graph'
    buttons to view an array of graphs of the voxel data time series.
    ++ The crosshairs in the image viewer that corresponds to the graph
       viewer change to a small box to indicate which voxels are the source
       of the data in the graph array.

(e) The viewpoint of multiple image and graph viewers (the focus voxel at the
    crosshairs) is always locked together -- Left-click in one image to move
    the crosshairs, and all other open image and graph viewers will jump, too.
    ++ Moving the time index in a graph viewer (by clicking in the central
       sub-graph, or by using the 'Index' control in the main AFNI window)
       will cause all the image and graph viewers to display at the new
       time index.

(f) At any moment, you can have one underlay dataset (grayscale) and one
    overlay dataset (color).  To choose which datasets are visible, use
    the 'UnderLay' and 'OverLay' button in the second column of the AFNI
    controller.
    ++ To control whether the color overlay is visible, click on the
       'See OverLay' toggle button.
    ++ To manage how the numbers in the overlay dataset are converted into
       colors, click on 'Define OverLay' to open up a new control panel.
    ++ The active underlay and overlay dataset names are shown in the title
       bar of the AFNI controller window.

(g) Don't be afraid of the software!  The popup hints will help.  The button
    'BHelp' will give you longer help about individual buttons -- click on
    the BHelp button, then click on any AFNI button to get a small text box
    with more help than the simple popup hints.

(h) Sample datasets and all the AFNI course materials are in the big file
    CD.tgz (more than 1 Gbyte) at
       https://afni.nimh.nih.gov/pub/dist/edu/data
    And don't forget the AFNI message board at
       https://discuss.afni.nimh.nih.gov

5.2.3. Cursor Shapes and Right-Click Popup Menus

On most systems, the X11 cursor used in AFNI is an orange arrow pointing at about ‘10:30’ on the clock face. However, the arrow becomes yellow and points more steeply, to about ‘11:00’, when it is over a location that has a hidden Right-Click popup menu. Some of these are:

(a) Over the logo square just to the right of the 'done' button in an
    AFNI controller.

(b) Over the labels at the top of the threshold slider and color bar in
    the 'Define Overlay' control panel.

(c) On the label to the left of a drop-down 'option menu'; e.g., 'Xhairs'
    or 'ULay' (for these menus, the cursor will not change shape).

(d) Over the color bar itself, when it is in continuous 'colorscale' mode
    ('**') -- but not when it is in discrete color panel mode.

(e) Over the image viewer main sub-window, which holds the image itself.

(f) Over the image viewer intensity bar, just to the right of the image.

(g) Over the 'Save' button in the image viewer.

(h) Over the 'crop' button in the image viewer.

(i) Over the sub-graphs in the time series dataset graph viewer
    (pops up some statistics about the data in the sub-graph).

(j) Over the coordinate display in the upper left corner of an AFNI
    controller.

(k) In the 'Render Dataset' plugin, over the 'See Xhairs' and 'Accumulate'
    toggle buttons.  The 'Accumulate' popup lets you enter a text label
    to be drawn in the rendered image viewer -- the actual display of labels
    (size and location) is controlled from the image viewer intensity bar
    popup menu -- item (e) above.  Right-Click lets you change the label
    for newly rendered images, whereas Shift+Right-Click lets you change
    the label for all previously rendered images as well as new images.

(l) In the 'Clusters' report panel, right-clicking in the upper part of
    the window (where the textual summary is), will let you choose how
    the 'Histog' option will plot the histogram from the 'Aux.Dset'.
    ('Histog' is selected from the menu whose initial choice is 'Mean'.)

5.2.4. Hidden Clicks to Activate AFNI Features

Other ‘special’ clicks that aren’t obvious:

(a) Left-clicking on the 'Image' or 'Graph' button for an already open
    AFNI viewer will bring that viewer's window back up to the top of
    the X11 window stacking order.

(b) Right-clicking on the 'Image' or 'Graph' button for an already open
    AFNI viewer will bring that viewer's window over to the place where
    you just clicked -- this is useful for finding lost viewers.

(c) Right-clicking on the 'DataDir' button in the AFNI controller will
    un-hide (or re-hide) the obsolescent 'Define Markers' button.

(d) Left-clicking on the logo at the lower left of a graph viewer will
    make the logo and menu buttons disappear -- this is intended to help
    you make a clean-looking snapshot of the window.  Left-click again
    in the same region at the lower left to un-hide the logo and buttons.

(e) Right-clicking on the graph viewer logo or on the image viewer 'Disp'
    button (i.e., the things at the lower left of each viewer window) will
    bring the parent AFNI controller back to the top of the X11 window
    stacking order.

(f) In an image viewer window, if you press-and-hold-down the Left mouse
    button, then drag the cursor vertically and horizontally (while still
    holding the Left button down), the contrast and brightness of the
    grayscale underlay changes as you move the mouse.

(g) To exit AFNI quickly when multiple controllers are open, hold down the
    Shift key when you press the 'done' button (in any AFNI controller).
    The usual requirement of pressing 'done' twice within 5 second is
    skipped, and all AFNI controllers exit immediately.

(h) Left-clicking in the logo square to the right of the AFNI controller
    'done' button will cause the AFNI splash screen to popup.  You can
    close the splash screen window again via the usual X11 controls on
    the window border, or by left-clicking again in the logo square.

5.2.5. Keyboard Shortcuts: Image Viewer Window

The AFNI image viewer has many keyboard shortcuts. Help for these can be found by using ‘BHelp’ and then clicking on the image sub-window itself. The shortcuts are used by putting the mouse cursor over the image sub-window and pressing the keyboard key.

  a = fix window aspect ratio        (= Left-click in intensity bar)
  c = enter cropping mode            (= clicking the 'crop' button)
  D = open Disp control panel        (= clicking the 'Disp' button)
  i = make the image sub-window smaller inside the overall viewer
  I = make the image sub-window larger
  l = left-right mirror image        (= '+LR Mirror' on Disp panel)
  m = toggle 'Min-to-Max' on/off     (= 'Min-to-Max' or '2%-to-98%' on Disp)
  M = open Montage control panel     (= clicking the 'Mont' button)
  o = color Overlay on/off           (= 'See Overlay' in AFNI controller)
  p = toggle panning mode            (= clicking the 'pan' button)
  q = close window                   (= clicking the 'done' button)
  r = like 'v', but image 'rebounds' when it reaches end of count
  R = like 'r', but backwards order
  s = sharpen underlay image         (= 'Sharpen' on the Disp control panel)
  S = save image                     (= clicking the 'Save' button)
  u = toggle background to be from Underlay or Overlay dataset
  v = automatically change images to make a 'video' (forwards order)
  V = same as 'v' but backwards order
  z = zoom out                       (= zoom down-arrow button)
  Z = zoom in                        (= zoom up-arrow button)
  [ = time index down by 1
  ] = time index up by 1
  { = lower AFNI statistical threshold slider
  } = raise AFNI statistical threshold slider
  > = PageUp = move forward one slice in image viewer
  < = PageDown = move backward one slice in image viewer
  # = toggle checkerboard pattern from underlay and overlay datasets
  3 = turn checkerboard pattern off
Keyboard arrow keys = move crosshairs (normal operation)
                    = pan zoomed window (when 'pan' is on)
Shift+arrow keys    = pan cropped region around
Ctrl+arrow keys     = expand/shrink cropped region
Home key            = center zoomed window on current crosshair location
Shift+Home          = center cropped region on current crosshair location
Del = undo in the Drawing plugin
 F2 = turn the Drawing pencil on
 F3 = subtract 1 from the Drawing plugin value
 F4 = add 1 to the Drawing plugin value
 F5 = Meltdown!
 F6 and higher are not (yet) defined.

5.2.6. Keyboard Shortcuts: Graph Viewer Window

The AFNI graph viewer also has many keyboard shortcuts.

     a = autoscale the graphs (this one time)
     A = autoscale the graphs (every time they are redrawn)
     b = switch graph baseline mode (between Separate, Common, and Global)
     B = switch on/off Boxes graphs instead of line graphs
     g = decrease vertical grid spacing in graphs
     G = increase vertical grid spacing in graphs
     h = draw dotted horizontal line at zero level in graphs
     i = decrease graph 'ignore' level by 1
     I = increase graph 'ignore' level by 1
     l = move to last time point
     L = turn AFNI logo on or off (but why would you want it OFF?!)
     m = reduce matrix size of sub-graphs by 1
     M = increase matrix size of sub-graphs by 1
     q = quit = Opt->Done
   r/R = 'rebound' up or down in time
     S = save an image of the graph window to a file
     t = show text (numbers) instead of graphs
   v/V = 'video' up or down in time
     w = write data from central sub-graph to a 1D file
     z = change slice number by 1 downwards (= keyboard Page Down key)
     Z = change slice number by 1 upwards   (= keyboard Page Up key)
     - = scale the graphs down (vertically)
     + = scale the graphs up
     1 = move to first time point
< or [ = move back in time by 1 point  (= keyboard Left arrow)
> or ] = move up in time by 1 point    (= keyboard Right arrow)
     N = after typing the 'N', type a number, then press Enter;
         the matrix of sub-graphs will change to the number given immediately
    F5 = Meltdown!

5.2.7. Keyboard Shortcuts in the Threshold Slider

Fine control over the threshold slider is hard with the mouse. You can move the slider with the following keystrokes, after clicking in the slider’s ‘thumb’ to move the keyboard input focus to this control.

  Down arrow = reduce slider by 1 in the 4th significant place
  Up arrow   = increase slider by 1 in the 4th significant place
  Page Down  = reduce slider by 1 in the 3rd significant place
  Page Up    = increase slider by 1 in the 3rd significant place
  Home       = drop slider to 0
  End        = move slider to top
The Left and Right arrow keys can similarly be used in the image viewer
slice index slider to move 1 slice backward or forward at a time.