Installation on MacOS - dwong263/MAGIQ GitHub Wiki

Before You Begin

  • These instructions are updated as of October 15, 2021.
  • PyGAMMA was updated to support Python 3.7, and these instructions reflect this.
  • These instructions were tested on a 2020 MacBook Pro with an M1 processor running MacOS 11 Big Sur. These instructions assume that your Mac has an M1 processor. Notes will be placed throughout to clarify which instructions are specific to the M1 Macs.

Installing the Basics

Install XCode and XQuartz

  • On MacOS, XCode is needed for Unix command line tools that will be used for installing libraries that MAGIQ depends on. To install XCode, download it from the Mac App Store. Ensure command line tools are enabled.
  • XQuartz is needed to run the both the IDL and FSL GUIs. Download and install XQuartz from here.

Setting up the Terminal on a Mac M1 Machine

Native and x86 Terminals

If you are using an Intel-based Mac, these instructions are not required. Simply use the native Terminal app for all installation steps.

If you are running a Mac M1 machine, you will need to first setup a Terminal that runs on the native ARM-based M1 hardware, and a Terminal that runs on top of Rosetta 2 which emulates Intel hardware. Please consult Apple Support This is needed because certain libraries that MAGIQ depends on are not yet supporting the M1 chip.

  1. Using Finder, find the Terminal app in Applications > Utilities.
  2. Duplicate the Terminal app. To do so, control click or right click the application and click Duplicate.
  3. Rename the duplicated Terminal app to something recognizabile like "Terminal (x86)". To do so, control click or right click the application and click Rename
  4. Control click or right clock "Terminal (x64)" and click Get Info.
  5. Select Open using Rosetta.

Moving forward, the original Terminal app will simply be referred to as "Terminal", while the duplicated Terminal app that is set to run on Rosetta will be referred to as "Terminal (x64)"

If you run the Terminal app and use the command arch, it will display arm64, signifying the the Terminal is running natively on the M1 chip, which is a 64-bit chip with an ARM-based architecture.

If you run the Terminal (x86) app and use the command arch, it will display i386, signifying that the Terminal is "seeing" an Intel-based architecture and is running on top of Rosetta 2.

Python

MacOS comes with Python 2.7.16 and Python 3.8.9 by default. Since a specific version of Python is required for PyGAMMA as well as the MATLAB Python Engine, installing Python via pyenv is recommended. Pyenv is most easily installed with homebrew.

Installing Homebrew

If you are using an Intel-based Mac, simply open up your Terminal app and run /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" to install Homebrew.

To install Homebrew, a package manager for MacOS, open up the Terminal app. Run the following commands:

  • arch --arm64 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  • arch —x86_64 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

The first command installs a version of Homebrew for packages that run natively on the M1 chip, while the second command installs a version of Homebrew for packages that run on Intel hardware. Each version of Homebrew is installed in unique paths by default.

Ensure the right version of Homebrew is run according to whether Terminal or Terminal (x86) is being used by adding the following to your ~/.zprofile:

# SETUP HOMEBREW PATHS
if [ "$(arch)" = "arm64" ]; then
    eval "$(/opt/homebrew/bin/brew shellenv)"
else
    eval "$(/usr/local/bin/brew shellenv)"
fi

Installing Pyenv

Pyenv is maintained at here. To install, follow the instructions below:

Install pyenv with homebrew. Run the following commands in both Terminal and Terminal (x86).

brew update
brew install pyenv

If you are using an M1 Mac, you can run the same commands in your Terminal.

Since pyenv was installed for both the M1 processor and for the emulated Intel processor, pyenv paths will conflict by default. Enusre this does not occur by adding the following to your ~/.zprofile:

# SETUP PYENV PATHS
if [ "$(arch)" = "arm64" ]; then
    export PYENV_ROOT="$HOME/.pyenv"
    export PATH="$PYENV_ROOT/bin:$PATH"
else
    export PYENV_ROOT="$HOME/.pyenv-x86"
    export PATH="$PYENV_ROOT/bin:$PATH"
fi
eval "$(pyenv init --path)"

This step is not needed if you are using an Intel-based Mac.

Installing Python 3.7.x via pyenv

MAGIQ will be installed and run within the Terminal (x86) app. Open Terminal (x86) and install Python 3.7.12 (or a later version if available):

pyenv install -v 3.7.12

Install IDL

IDL is required to run the fitMAN GUI. From the L3Harris Geospatial Download and License Center, download the command line installer for MacOS. Ensure the version of IDL is ≥ 8.8.1 for native M1 support.

Since IDL can run natively on an M1 Mac, install it with the native Terminal app, not Terminal (x86).

If you are running an Intel-based Mac, simply follow the next few instructions in your Terminal.

In a Terminal window, navigate to the IDL folder, extract the archive, and run the installation script and follow the prompts.

tar -xzvf idl873-mac.tar.gz
sudo ./install.sh

Notes:

  • When it asks you for an installation path, simply hit enter to install in the default location.
  • Answer 'n' when you are asked to install ENVI, ENVI Classic help files, ENVI Help files, DICOM Network Services, or when you are asked to run the License Manager. Answer 'y' for all other queries.

Test the IDL installation by running:

idl -vm

A splash screen should pop up after running this command. Hit "Ok" on the splash screen and another dialog box should pop up asking you to select an IDL save file. If this happens, the IDL virtual machine was installed correctly. You can close the dialog box.

Install Git

To download code from GitHub, you will need git. Install git using the following command:

brew install git

This can be done in the native Terminal app.

Obtaining the Software

Downloading a Specific Version

You can download a specific version of the software via the "Releases" page (https://github.com/dwong263/MAGIQ/releases). Place this source code into an easily locatable folder and and extract it. This folder will be referred to as the <Software Folder> in subsequent instructions.

Using Git

You can use git to clone the GitHub repository and obtain the software. This allows you to contribute to the code development and easily pull the latest changes onto your computer.

  1. To keep all the software in one place, it is suggested that you install MAGIQ within an easily locatable folder. This folder will be referred to as the <Software Folder> in subsequent instructions.
  2. Navigate to that folder in a Terminal window (cd <Software Folder>) and clone the MAGIQ repository:
git clone https://github.com/dwong263/MAGIQ

These commands can be done in the native Terminal app.

Setting the Local Environment

Recall that MAGIQ will be installed and run within the Terminal (x86) app using Python 3.7. Using Terminal (x86), navigate to <Software Folder>/MAGIQ and set the local python environment to use Python 3.7.12 (or whichever version of Python 3.7 you installed):

cd <Software Folder>/MAGIQ
pyenv local 3.7.12

If you are using an Intel-based Mac, you can use the same instructions in the Terminal app.

Install MAGIQ Dependencies

The Simple Stuff

Notes:

  • If you are using an M1 Mac, use the Terminal (x86) app to run the commands in this section.
  • If you are using an Intel Mac, just simply run the commands in your Terminal app.
  • Ensure you are running the following commands in the <Software Folder>/MAGIQ folder, so these dependencies are installed for Python 3.7.

###Upgrade pip

pip install --upgrade pip

###Install PyQt5

brew install qt
brew install swig
pip install PyQt5

###Install scipy and numpy

pip install scipy

###Install matplotlib

pip install matplotlib

###Install pyfftw

pip install pyfftw

###Install NiBabel

pip install nibabel

###Install future

pip install future

###Install PyGAMMA

pip install PyGAMMA

The More Complicated Stuff

FSL

Download the fslinstaller.py script from the FSL website. Since FSL can run natively, use the normal Terminal app instead of the Terminal (x86) app for these instructions.

If you are using an Intel-based mac, simply follow these instructions using your Terminal app.

  • Navigate to the location of fslinstaller.py
  • Set the local python environment to version 2.7.18. This is necessary as the FSL installation script requires Python 2.7 to run properly.
pyenv local 2.7.18
  • Run the installer. sudo or administrative priveleges may be required for this operation.
python fslinstaller.py
  • Configure your shell by adding the following lines to ~/.zproflie:
FSLDIR=/usr/local/fsl
. ${FSLDIR}/etc/fslconf/fsl.sh
PATH=${FSLDIR}/bin:${PATH}
export FSLDIR PATH

  • Finally, check the FSL installation:

    1. Open a new Terminal window and check that your environment is correct by typing echo $FSLDIR.
    2. Check that your path is correct by running an FSL command such as flirt --version.
    3. Check that the FSL GUI applications launch normally by running a command such as fsleyes or fsl.

###ultra_fitman ultra_fitman is the script called by fitMAN that performs the fitting of prior knowledge template to magnetic resonance spectra data. A pre-compiled version that (should) work is available in <Software Folder>/MAGIQ/fitman/bin/MacOS/ultra_fitman.

Test whether or not it works by navigating to this folder and running ./ultra_fitman. If it runs successfully, simply copy this file to <Software Folder>/MAGIQ/fitman/bin. This is the path that fitMAN looks for when calling the script.

If it doesn't work, compile it for yourself. ultra_fitman was written ages ago, and is not updated for running on an M1-based Mac. Thus, if you are using an M1-based Mac, compile it under the Terminal (x86) app. Otherwise, just run these instructions in the default Terminal app.

  • In the Terminal (x86) app, navigate to the directory <Software Folder>/MAGIQ/fitman/src/ultra_fitman and compile with the following commands:
cd /Users/dwong/Documents/Software/GitHub/MAGIQ/fitman/src/ultra_fitman
g++ src/*.cpp -L/usr/lib -I./src -lm -o ultra_fitman
  • Then, copy the produced ultra_fitman executable to <Software Folder>/MAGIQ/fitman/bin.

Launch MAGIQ

Your installation is now complete! Close your Terminal window and open a new one.

  • If you are using an Intel-based Mac, simply use your Terminal app to run MAGIQ.
  • If you are using an M1 Mac, always run MAGIQ within Terminal (x86).

Navigate to the folder containing the MAGIQ files (<Software Folder>/MAGIQ) and launch the program with the following commands:

python main.py

You can launch the individual programs of the MAGIQ Software Suite using:

python pints.py
python apps.py
python fitman.py
python spices.py
python barstool.py

Special Instructions for the Rodent Version of BARSTOOL

The "Rodent Version" of BARSTOOL (BARSTOOL-RV) requires MATLAB with the MATLAB Engine API for Python installed, as it relies on a pulse-coupled neural network (PCNN-3D) implemented in MATLAB for rodent brain extraction. Obviously, you wil need to download and install MATLAB.

MATLAB Engine API for Python does not yet support the M1 chip natively. You will need to install it using Terminal (x86) if you are using a M1 Mac. If you are running an Intel-based mac, use the default Terminal app.

  • In a Terminal (x86) window navigate to /Applications/MATLAB_R2021b.app/extern/engines/python. At the time of writing of these instructions, the latest MATLAB version available was MATLAB R2021b. Ensure the path is correct for your version of MATLAB.
  • Execute the following commands. You may need sudo or administrative privileges to do this.
cd <MATLAB Root Folder>/extern/engines/python
pyenv local 3.7.12
python setup.py install
  • Ensure you have the MATLAB NIFTI tools downloaded and on your MATLAB path.