Installation on macOS#

These instructions will help you install a working version of QuNex on a macOS system.

The strategy employed is to:

  1. Install QuNex in /usr/local/qunex

  2. Install all the dependencies in their default locations and sym-link them to /usr/local to set up QuNex access

  3. Edit the configuration files

We are assuming your user has administration or sudo privileges and the default shell is bash.

1. Install QuNex#

Clone the latest QuNex repository to /usr/local/qunex:

sudo su
cd /usr/local
git clone git@gitlab.qunex.yale.edu:qunex/qunex.git
cd qunex
git submodule init
git pull --recurse-submodules && git submodule update --recursive
git submodule foreach git pull origin master

2. Install all the dependencies#

Prerequisites#

X-code#

xcode-select --install

XQuartz#

Download the .dmg package from http://www.xquartz.org/ and follow instructions to install.

Homebrew#

ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" \
< /dev/null 2> /dev/null

wget#

brew install wget

R#

Download and install the latest version of R from https://www.r-project.org:

sudo r
install.packages("ggplot2", dependencies=TRUE)

AFNI#

# -- Prepare the target folder and download the installer
sudo su
cd /usr/local
mkdir afni
cd afni
curl -O https://afni.nimh.nih.gov/pub/dist/bin/macosx_10.7_local/@update.afni.binaries

# -- Run the installer
# for macOS 10.12 or higher
tcsh @update.afni.binaries -package macos_10.12_local -bindir /usr/local/afni/afni-latest
# for macOS < 10.12
tcsh @update.afni.binaries -package macos_10.7_local -bindir /usr/local/afni/afni-latest

# -- Add the following to your .bash_profile or /etc/profile
export PATH=/usr/local/afni/afni-latest:$PATH

# -- Install supporting apps and packages
rPkgsInstall -pkgs ALL
brew install netpbm

For additional up-to-date information consult https://afni.nimh.nih.gov/pub/dist/doc/htmldoc/background_install/install_instructs/steps_mac.html.

FSL#

Use the form at https://fsl.fmrib.ox.ac.uk/fsldownloads_registration to register and download the fslinstaller.py script:

sudo python <path to fslinstaller.py>

If the above command returns [SSL: CERTIFICATE_VERIFY_FAILED] error, run:

sudo PYTHONHTTPSVERIFY=0 
sudo python <path to fslinstaller.py>

FreeSurfer#

Download the following two packages:

Open the v6.0.0 .dmg file and run the installer. Once it finishes run:

sudo mkdir /usr/local/freesurfer
sudo mv /Applications/freesurfer /Applications/freesurfer-6.0.0
sudo ln -s /Applications/freesurfer-6.0.0 /usr/local/freesurfer

Open the v5.3.0-HCP .dmg file and run the installer. Once it finishes run:

sudo mv /Applications/freesurfer /Applications/freesurfer-5.3-HCP
sudo ln -s /Applications/freesurfer-5.3-HCP /usr/local/freesurfer

Get a licence file by filling out the form at: https://surfer.nmr.mgh.harvard.edu/registration.html and follow instructions. Apply the licence to both installations.

dcm2niix#

Get the latest copy of the MRIcroGL package at https://www.nitrc.org/projects/mricrogl/. Open the downloaded .dmg package and copy/drag the MRIcroGL folder to /Applications. Then run:

sudo mkdir /usr/local/dcm2niix
sudo ln -s /Applications/MRIcroGL /usr/local/dcm2niix/dcm2niix-latest

dicm2nii#

To install dicm2nii run:

sudo su
mkdir /usr/local/dicm2nii
cd /usr/local/dicm2nii
git clone https://github.com/xiangruili/dicm2nii
mv dicm2nii dicm2nii-latest

# -- To save json files by default
sed -i -e "s|'dicm2nii_gui_para', 'save_json', false|'dicm2nii_gui_para', 'save_json', true|g" \ 
dicm2nii-latest/dicm2nii.m

Be aware that on the first run for each user, dicm2nii will generate the default parameter file and the first conversion might fail. If that happens, just run the command again. Also note that dicm2nii has only been tested with MATLAB and Octave might not be supported.

fix#

To set up fix, run the following:

sudo su
cd /usr/local/fsl
wget http://www.fmrib.ox.ac.uk/~steve/ftp/fix.tar.gz
tar xvfz fix.tar.gz
rm fix.tar.gz

# -- Link the latest fix version to fix
if [ -d "fix" ]; then rm -r "fix" ; fi
fixfolder=(`ls -d fix*`)
ln -sF ${fixfolder[@]: -1} fix-latest

# -- Install the needed R packages
r
install.packages("kernlab", dependencies=TRUE)
install.packages("ROCR", dependencies=TRUE)
install.packages("class", dependencies=TRUE)
install.packages("party", dependencies=TRUE)
install.packages("e1071", dependencies=TRUE)
install.packages("randomForest", dependencies=TRUE)

Octave#

To install Octave and packages run:

sudo su
brew install octave

# -- Link the latest Octave version to the desired location
mkdir /usr/local/Octave
octdir=(`ls -d /usr/local/Cellar/octave/*`)
octdir=${octdirs[@]: -1}
ln -s octdir /usr/local/Octave/octave-latest

# -- Install packages within octave
mkdir /usr/local/octavepkg

octave
pkg prefix /usr/local/octavepkg
pkg local_list /usr/local/octavepkg/packages

pkg install -local -forge control
pkg install -local -forge general
pkg install -local -forge image
pkg install -local -forge io
pkg install -local -forge nan
pkg install -local -forge signal
pkg install -local -forge statistics
pkg install -local -forge struct
pkg install -local -forge optim
pkg install -local -forge miscellaneous
exit

# -- Compile QuNex mex files
cd /usr/local/qunex/matlab/qx_mri/img/@nimage

# -- Prepare files for compilation
cp img_read_nifti_mx_octave.cpp img_read_nifti_mx.cpp
cp img_save_nifti_mx_octave.cpp img_save_nifti_mx.cpp

# -- Compile .mex files within octave
octave
mkoctfile --mex -lz -std=c++11 img_read_nifti_mx.cpp qx_nifti.c znzlib.c
mkoctfile --mex -lz -std=c++11 img_save_nifti_mx.cpp qx_nifti.c znzlib.c
exit

# -- Remove temporary files
rm img_read_nifti_mx.cpp
rm img_save_nifti_mx.cpp
rm qx_nifti.o 
rm znzlib.o

Python libraries#

sudo su
pip install numpy pydicom scipy nose sphinx futures -t /usr/local/pylib

# -- Setup pylib folder
mkdir /usr/local/pylib
cd /usr/local/pylib

# -- Install nibabel
wget https://github.com/downloads/ksubramz/gradunwarp/nibabel-1.2.0.dev.tar.gz
tar xvfz nibabel-1.2.0.dev.tar.gz
rm nibabel-1.2.0.dev.tar.gz
mv nibabel-1.2.0.dev nibabel
cd nibabel 
sudo python setup.py install

# -- Install gradunwarp
cd /usr/local/pylib
wget https://github.com/Washington-University/gradunwarp/archive/v1.1.0.tar.gz
tar xvfz v1.1.0.tar.gz
rm v1.1.0.tar.gz
mv gradunwarp-1.1.0 gradunwarp
cd gradunwarp 
sudo python setup.py install

Connectome Workbench#

Download Connectome Workbench from https://humanconnectome.org/software/get-connectome-workbench, unzip it and move it to /Applications.

Run:

sudo su
mkdir /usr/local/workbench
ln -s /Applications/workbench/bin_macosx64 /usr/local/workbench/workbench-latest

3. Edit the configuration files#

Add the following lines to /etc/profile (and adjust when needed):

export TOOLS="/usr/local"
export FSLFolder="${TOOLS}/fsl/fsl-latest"
export FIXICAFolder="${TOOLS}/fsl/fix-latest"
export FREESURFERDIR="${TOOLS}/freesurfer/freesurfer-5.3-HCP"
export FSDIR53HCP="${TOOLS}/freesurfer/freesurfer-5.3-HCP"
export FSDIRLATEST="${TOOLS}/freesurfer/freesurfer-6.0.0"
export HCPWBDIR="${TOOLS}/workbench/workbench-latest"
export AFNIDIR="${TOOLS}/afni/afni-latest"
export DCMNII="${TOOLS}/dcm2niix/dcm2niix-latest"
export DICMNII="${TOOLS}/dicm2nii/dicm2nii-latest"
export OCTAVEDIR="${TOOLS}/Octave/octave-latest"
export OCTAVEPKGDIR="${TOOLS}/octavepkg"
export PYLIBDIR="${TOOLS}/pylib"

export QUNEXREPO='qunexs'
export QUNEXPATH="$TOOLS/$QUNEXREPO"

# set up QuNex environment
source $QUNEXPATH/env/qunex_environment.sh