1.1.9. macOS 12+ (Intel processor/chip)

What to do?

These setup instructions are for macOS 12 or greater with Intel CPUs (not Apple Silicon).

  1. To verify your processor/chip type, you can click on the Apple icon in the upper left of the screen -> “About this Mac”, and check the “Processor” or “Chip” type listed.

  2. Each step involves copy+pasting text into a terminal (the Terminal app, which can be found via the Finder). This text is highlighted in a green field like:

    ls

    In some cases, clicking/typing in an app is necessary, as well as rebooting the computer for changes to take effect.

  3. If you need to know your shell type, copy+paste echo $0.

Quick setup (General users)

This section describes primary installation instructions for general users, and it is assumed that you have administrative/sudo privileges on your macOS computer:

  1. Copy+paste the following to get download scripts:

    cd
curl -O https://raw.githubusercontent.com/afni/afni/master/src/other_builds/OS_notes.macos_12_intel_a_admin_pt1.zsh
curl -O https://raw.githubusercontent.com/afni/afni/master/src/other_builds/OS_notes.macos_12_intel_a_admin_pt2.zsh
curl -O https://raw.githubusercontent.com/afni/afni/master/src/other_builds/OS_notes.macos_12_intel_b_user.tcsh

  2. Copy+paste the following to run the first admin-level install script (which will ask you to enter your administrator password, twice (once early, once later)):

    zsh OS_notes.macos_12_intel_a_admin_pt1.zsh

  3. Copy+paste the following to run the second admin-level install script (which will ask you to enter your administrator password):

    zsh OS_notes.macos_12_intel_a_admin_pt2.zsh

  4. Reboot the computer (for the changes to take effect).


  5. Copy+paste the following to run the user-level install script (no password required):

    tcsh OS_notes.macos_12_intel_b_user.tcsh

  6. To get additional Python libraries used in AFNI, it currently appears most efficient on macOS to use conda (e.g., Miniconda or Anaconda). Quick Miniconda Setup instructions are provided, with the necessary set of Python libraries provided for an environment (e.g., in “environment_ex1.yml”). These could be added to an existing environment, or used to create a new one. NB: this should be done after AFNI binaries have been compiled.

Quick setup (special case: NIMH-administered computers)

This section describes primary installation instructions for the special case of having a macOS computer administered by NIMH (NIH, USA), where the user does not have admin privileges:

  1. Use the NIMH Self Service application to install the dependencies needed by AFNI (PIV-card required):

    1. Open the NIMH Self Service App on the Mac

    1. Type AFNI in the search bar:

    1. Click “Install” for “AFNI Dependencies”
    ../../_images/img_nimh_selfservice_app.png ../../_images/img_nimh_selfservice_app_afni_icon.png

    NB: The App finishes subtly, just changing text to read “Reinstall”. When it completes, carry on to further installation stages below.

    Thanks to the NIMH Mac Engineering team for helping to set this set of instructions up.


  2. Copy+paste the following to get a download script:

    cd
curl -O https://raw.githubusercontent.com/afni/afni/master/src/other_builds/OS_notes.macos_12_intel_b_user.tcsh

  3. Copy+paste the following to run the user-level install script (no password required):

    tcsh OS_notes.macos_12_intel_b_user.tcsh

  4. To get additional Python libraries used in AFNI, it currently appears most efficient on macOS to use conda (e.g., Miniconda or Anaconda). No administrator password is needed for this. Quick Miniconda Setup instructions are provided, with the necessary set of Python libraries provided for an environment (e.g., in “environment_ex1.yml”). These could be added to an existing environment, or used to create a new one. NB: this should be done after AFNI binaries have been compiled.

Evaluate setup/system (important!)

  1. Open a new terminal, and then copy+paste:

    afni_system_check.py -check_all
  2. Read the “Please Fix” section at the end. If there are no suggestions, then rejoice! Otherwise, try the suggestion(s) there.

  3. Open up the AFNI and SUMA GUIs, juuuust to make sure all is well:

    afni
suma

Report any crashes or problems!

If stuck, then …

  • try searching online with the error message, and/or ask on the Message Board

  • send the system check to an AFNI guru for advice—copy+paste:

    afni_system_check.py -check_all > out.ASC.txt

    ... and email the file “out.ASC.txt”.

Optional Extras

Setup Python (a method)

AFNI has very minimal Python requirements—at present, matplotlib and numpy. For example, for the recommended automatic QC output from afni_proc.py, matplotlib is necessary.

You can use any method to install+manage Python and its dependencies. In fact, your OS might have all the Python+modules needed to run AFNI already. Check this by running:

afni_system_check.py -check_all

... and seeing there are no notes in the “Please fix” section at the end—if there are none about Python, then you are all set!

But if you do still need to setup Python with appropriate modules, or you want to manage different environments with different package needs (Python or otherwise), then we note that we have found Miniconda to be convenient. It is cross-platform (with occasional OS-specific quirks). If you are interested in either using it or reading more about it, you can check out this tutorial, which has both verbose and quick instructions.

But Miniconda is not required.

Prepare for Bootcamp (install demo data)

The AFNI Bootcamp involves hands-on learning with processing and looking at data. The packages installed here include the data, handouts and useful “cheat sheets” of commands. The full download size is several GB, and you should leave at least 10 GB free on your computer after downloading+unpacking the data, to be able to run various examples.

  1. Copy+paste (to download+upack Bootcamp data to your home directory):

    cd
curl -O https://afni.nimh.nih.gov/pub/dist/edu/data/CD.tgz
tar xvzf CD.tgz
cd CD
tcsh s2.cp.files . ~
cd ..

  2. Copy+paste (to download+upack data for investigating QC in FMRI):

    cd
curl -O https://afni.nimh.nih.gov/pub/dist/edu/data/boot_qc/bootcamp_qc_sub_rest_A.tgz
curl -O https://afni.nimh.nih.gov/pub/dist/edu/data/boot_qc/bootcamp_qc_sub_rest_B.tgz
curl -O https://afni.nimh.nih.gov/pub/dist/edu/data/boot_qc/bootcamp_qc_sub_task_A.tgz
tar -xf bootcamp_qc_sub_task_A.tgz
tar -xf bootcamp_qc_sub_rest_A.tgz
tar -xf bootcamp_qc_sub_rest_B.tgz

  3. If no errors occur in the above, and your afni_system_check.py says things are OK, you can delete/remove the tarred/zipped package, using:

    cd
rm CD.tgz
rm bootcamp_qc_sub_task_A.tgz
rm bootcamp_qc_sub_rest_A.tgz
rm bootcamp_qc_sub_rest_B.tgz
    If you are confident in the downloads+unpacking, you can also deleted the CD/ directory in the present location.

  4. !Pro tip!: Bring a computer mouse to use at the Bootcamp. It is muuuuch easier to follow the demos that way.

  5. Read+practice the handy Unix documentation/tutorial. This will give you a quick lesson/refresher on using basic Linux shell commands (e.g., ls, cd, less, etc.). It will greatly enhance your bootcamp experience– we promise!

Setup terminal (opt)

  1. Copy+paste:

    defaults write org.macosforge.xquartz.X11 wm_ffm -bool true
defaults write org.x.X11 wm_ffm -bool true
defaults write com.apple.Terminal FocusFollowsMouse -string YES

    Purpose: This sets the policy where “focus follows mouse” for relevant applications. After this, clicks on a new window are directly applied, without needing to “pre-click” it. You’re welcome.

Niceify terminal (add convenience!)

To improve your life when using the terminal, copy+paste these:

echo 'set filec'    >> ~/.cshrc
echo 'set autolist' >> ~/.cshrc
echo 'set nobeep'   >> ~/.cshrc

echo 'alias ls ls -G'       >> ~/.cshrc
echo 'alias ll ls -lG'      >> ~/.cshrc
echo 'alias ltr ls -lGtr'   >> ~/.cshrc
echo 'alias ls="ls -G"'     >> ~/.bashrc
echo 'alias ll="ls -lG"'    >> ~/.bashrc
echo 'alias ltr="ls -lGtr"' >> ~/.bashrc
echo 'alias ls="ls -G"'     >> ~/.zshrc
echo 'alias ll="ls -lG"'    >> ~/.zshrc
echo 'alias ltr="ls -lGtr"' >> ~/.zshrc

Purpose: The first command block sets up tab autocompletion for tcsh (which should already be enabled for bash users by default). The second set of commands make aliases for the main shells so that different types of files (“normal” files, zipped files, executables, et al.) and directories are shown using different colors and boldness. It makes it much easier to navigate on a terminal, IMHO.

Keep up-to-date (remember!)

  1. To update your AFNI sometime, copy+paste:

    @update.afni.binaries -d

    That’s it!!

    Purpose: This will automatically download the correct, latest AFNI version to your computer, replacing your old binaries. It will also update the apearch help information. Update often!

  2. To check your AFNI version, copy+paste:

    afni -ver

    Purpose: Report this useful info whenever asking a question on the Message Board!

Note

The record of all changes (new options, new programs, bug fixes, et al.) in AFNI programs is maintained for all to see in the online AFNI History.