1.2.1. macOS 12+ (Silicon/ARM chip: M1, M2, …), administered system

Overview

These setup instructions are for particular macOS systems:

  • version: macOS 12 or greater

  • chip: Silicon/ARM compiler (M1, M2, M3, M4, …)

  • an administered computer, meaning that the user does not have “root” privileges but they work with an administrator who does.

  • the computer is not an NIMH-administered one, for which there are specific instructions for macOS 12 or greater with Silicon/ARM CPUs here.

If you have any questions about this or other installation issues, please ask us on the Message Board.

Here are a few notes that might be useful user users and admins alike:

  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.

Part 1: for the administrator

Here we describe the administrator’s part of the AFNI installation, which must be performed prior to the user’s part. Root privilege is required for the steps in this section.

Install dependencies

  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_ARM_a_admin_pt1.zsh
curl -O https://raw.githubusercontent.com/afni/afni/master/src/other_builds/OS_notes.macos_12_ARM_a_admin_pt2.zsh

  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_ARM_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_ARM_a_admin_pt2.zsh

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

Part 2: for the regular user

Here we describe the regular (= administrator) user’s part of the AFNI installation, which must be performed after the administrator’s part. Root privilege is not required for the steps in this section.

Install AFNI

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

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

    tcsh OS_notes.macos_12_ARM_b_user.tcsh

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

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.