Chapter 1 Installing Programs

These programs will be installed on the remote computer system (either Helix or Arc). At the end are the programs that you need to install on your local computer.

1.1 Remote

1.1.1 Prepare your home directory

Within your home directory on the remote computer make two directories. One to store the source code (build directory) and one to store the binary code once the programs are complied (apps). If it makes more sense you can name the build directory, source, but essentially these are the files that you will use to build your applications.

mkdir ~/build
mkdir ~/apps

1.1.2 Cmake v3.13.3

The cluster has several versions of cmake avaliable, the default version is 2.8.12.3. You can load alternative versions through modules, but those still aren’t current enough for our purposes. For ANTs, you need at least Cmake version 3.12. Cmake is the program used to compile programs from source code; Cmake is the program that helps install applications.

cd ~/build
wget https://github.com/Kitware/CMake/releases/download/v3.13.3/cmake-3.13.3-Linux-x86_64.tar.gz
tar xzfv cmake-3.13.3-Linux-x86_64.tar.gz -C ~/apps

Using your preferred Terminal text editor (my preferred is vi), add these lines to your .bash_profile. Remember that Vi launches in command mode. Press ‘a’ to enter into insert mode. Press ‘esc’ to exit insert mode. Type :wq and press enter to save the file and quit. If you don’t want to save a file that’s been edited type :q!.

# CMAKE
export PATH="/home/ashley.ware/apps/cmake-3.13.3-Linux-x86_64/bin:$PATH"

To reload your .bash_profile.

source ~/.bash_profile

1.1.3 ANTs

Download the latest code from the Github repository:

cd ~/build
git clone https://github.com/stnava/ANTs.git
mkdir -p ~/apps/ants
cd ~/apps/ants
ccmake ../../build/ANTs

When the CMake program launches, hit ‘c’ to do an inital configuration. CMake will do some checking and then present options for review. Hit ‘c’ again to do another round of configuration. If there are no errors, you’re ready to generate the make files by pressing ‘g’. For installation on your system, you probably don’t need to make changes to the options.

Now you are back at the command line, it’s time to compile.

make

The system will build ITK and then ANTs. Using these default settings, installation will take approximately 40 minutes. The final step will be to copy the scripts from the source directory to the bin directory.

cp -vr ~/build/ANTs/Scripts/* ~/apps/ants/bin/

Assuming you’ve put your source files in ~/build/ANTs, there will now be a binary directory ~/apps/ants/bin, containing the programs (and scripts if you’ve included them). The scripts additionally require ANTSPATH to point to the bin directory including a trailing slash.

# ANTS
export ANTSPATH=/home/ashley.ware/apps/ants/bin/
PATH=${ANTSPATH}:${PATH}

Now check this works.

which antsRegistration

should print out the full path to antsRegistration, and

antsRegistrationSyN.sh

should print out the usage for that script. You can put the above variable definitions in your shell initialization file, .bash_profile, so future sessions will have them set automatically.

1.1.4 FreeSurfer 6.0 Stable Version

cd ~/build
wget URL

The URL is https://surfer.nmr.mgh.harvard.edu/pub/dist/freesurfer/6.0.0/freesurfer-Linux-centos6_x86_64-stable-pub-v6.0.0.tar.gz

Installing FreeSurfer on Linux systems involves simply extracting the contents of the .tar.gz file to your apps directory.

tar -xzvf freesurfer-Linux-centos6_x86_64-stable-pub-v6.0.0.tar.gz -C ~/apps/

To begin using FreeSurfer, you need to open a terminal window and define and environment variable called FREESURFER_HOME which is set to the location FreeSurfer was installed, and then source the setup script. Sourcing FreeSurfer needs to be done every time you open a new terminal window. Or, you can add the two lines below to your default setup file (.bash_profile) and FreeSurfer will be sourced automatically every time you open a new window.

# FREESURFER
export FREESURFER_HOME="/home/ashley.ware/apps/freesurfer"
source $FREESURFER_HOME/SetUpFreeSurfer.sh

If done correctly, when you open a new window or type source ~/.bash_profile you should see output similar to this.

-------- freesurfer-Linux-centos6_x86_64-stable-pub-v6.0.0-2beb96c --------
Setting up environment for FreeSurfer/FS-FAST (and FSL)
FREESURFER_HOME   /home/ashley.ware/apps/freesurfer
FSFAST_HOME       /home/ashley.ware/apps/freesurfer/fsfast
FSF_OUTPUT_FORMAT nii.gz
SUBJECTS_DIR      /home/ashley.ware/apps/freesurfer/subjects
INFO: /home/ashley.ware/matlab/startup.m does not exist ... creating
MNI_DIR           /home/ashley.ware/apps/freesurfer/mni

A license key must be obtained to make the FreeSurfer tools operational. Obtaining a license is free and comes in the form of a license.txt file. Once you obtain the license.txt key file, copy it to your FreeSurfer installation directory. This is also the location defined by the FREESURFER_HOME environment variable.

Follow this link to obtain a license

You will have to create the new file and copy and paste the code from your email into the file.

vi ~/apps/freesurfer/license.txt

You can double check your installation with the following code.

cd ~/apps/freesurfer/subjects
mri_convert sample-001.mgz sample-001.nii.gz

1.1.5 FreeSurfer Developmental Versions

For some new ROIs and features you’ll want the latest developmental version of FreeSurfer. We can install multiple versions of programs luckily. Do not change your .bash_profile. When you submit jobs to the computing clusters, you can include in your environmental variables either FreeSurfer version.

cd ~/build
wget https://surfer.nmr.mgh.harvard.edu/pub/dist/freesurfer/dev/freesurfer-linux-centos6_x86_64-dev.tar.gz
mkdir -p ~/apps/freesurfer-dev
tar -xzvf freesurfer-linux-centos6_x86_64-dev.tar.gz \
-C ~/apps/freesurfer-dev --strip-components 1

1.1.6 Convert3D

cd ~/build
wget https://sourceforge.net/projects/c3d/files/c3d/Nightly/c3d-nightly-Linux-x86_64.tar.gz
tar -xvzf c3d-nightly-Linux-x86_64.tar.gz -C ~/apps/

Using your preferred Terminal text editor, add these lines to your .bash_profile.

# CONVERT3D
export PATH="/home/ashley.ware/apps/c3d-1.1.0-Linux-x86_64/bin:$PATH"

To reload your .bash_profile.

source ~/.bash_profile

You can test your installation.

c3d -h

1.1.7 Statistical Parametric Mapping (SPM)

This is a MATLAB toolbox. This is how you install all MATLAB toolboxes. You simply download and store the files in an easily remembered location. In this case, we’ll create a matlab folder under the apps folder and store all the MATLAB toolboxes there. Download the zip files and unzip. That’s it.

mkdir -p ~/apps/matlab/
cd ~/apps/matlab
wget http://www.fil.ion.ucl.ac.uk/spm/download/restricted/contradistinction/spm5.zip
unzip spm5.zip && rm spm5.zip
wget http://www.fil.ion.ucl.ac.uk/spm/download/restricted/idyll/spm8.zip
unzip spm8.zip && rm spm8.zip

1.1.8 VistaSoft

This is another MATLAB toolbox. Installation is straight-forward.

cd ~/apps/matlab
git clone https://github.com/vistalab/vistasoft.git

1.1.9 AFQ

AFQ is also a MATLAB toolbox (for the time being). Eventually it’ll be a Docker container.

cd ~/apps/matlab
git clone https://github.com/yeatmanlab/AFQ.git

1.1.10 FSL

You will need to download the installer from the website and upload the file to your account. Follow the link to download the installer. On your local computer type the following.

scp ~/Downloads/fslinstaller.py ashley.ware@helix.hpc.ucalgary.ca:~/build/

Then once you’ve logged back into the computing cluster, remote computer, you can run the installer.

cd ~/build/
python fslinstaller.py

When asked where to install fsl, type your absolute path to the directory.

/home/ashley.ware/apps/fsl

You can check installations.

source ~/.bash_profile
echo $FSLDIR
module load openblas/0.2.20-gnu 
flirt

One thing I’ve noticed is the occasional glitch to this version of FSL. The other way to install FSL:

module load fsl/6.0
source /global/software/fsl/fsl_6.0/etc/fslconf/fsl.sh

FSL has been made avaliable globally for all HPC users. On a Linux these apps are typically avaliable to install via modules, which contain all the necessary environmental variables and information for using the program.

1.1.11 Mindboggle

To convert the Docker to Singularity module, on your local computer first install Homebrew if you haven’t done that already.

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Next, install Vagrant and the necessary bits.

brew cask install virtualbox
brew cask install vagrant
brew cask install vagrant-manager

If you want to get more familiar with how Vagrant and VirtualBox work, you can instead build your own Vagrant Box from scratch. In this case, we will use the Vagrantfile for bento/centos-6. As before, you should first make a separate directory for your Vagrantfile, and then init a base image.

cd ~/Desktop
mkdir singularity
cd singularity
vagrant init bento/centos-6

Next, build and start the vagrant hosted VM, and you will install Singularity by shell into the box with vagrant ssh. Then run these commands on your own.

vagrant up --provider virtualbox
# Run the necessary commands within the VM to install Singularity
vagrant ssh -c /bin/sh
sudo yum update
sudo yum -y install rpm-build gcc wget
sudo yum -y install git libtool automake autoconf make
sudo yum -y install build-essential curl git sudo man vim autoconf libtool
sudo yum install libarchive-devel
sudo yum install squashfs-tools
git clone https://github.com/sylabs/singularity.git
cd singularity
git checkout -t origin/vault/release-2.6
./autogen.sh
./configure --prefix=/usr/local
make
sudo make install

Convert Docker to Singularity.

cd ~
sudo /usr/local/bin/singularity build mindboggle.img docker://nipy/mindboggle

In a new terminal window.

vagrant plugin install vagrant-scp
cd ~/Desktop/singularity
vagrant scp :mindboggle.img ~/Desktop/

Once you’ve downloaded the image.

vagrant halt

On your local computer upload the image to your remote computer.

scp ~/Desktop/mindboggle.img ashley.ware@helix.hpc.ucalgary.ca:~/apps

You can run the container on the remote computer.

singularity run \
--bind /home/ashley.ware:/home/jovyan/work \
/home/ashley.ware/apps/mindboggle.img

And check if mindboggle will run.

mindboggle -h

1.1.12 MRIQC

This process will be similar to Mindboggle.

cd ~/Desktop/singularity
vagrant up --provider virtualbox
vagrant ssh -c /bin/sh
sudo /usr/local/bin/singularity build mriqc.img docker://poldracklab/mriqc:latest

In a new terminal window.

cd ~/Desktop/singularity
vagrant scp :mriqc.img ~/Desktop/

Once you’ve downloaded the image.

vagrant halt

On your local computer upload the image to your remote computer.

scp ~/Desktop/mriqc.img ashley.ware@helix.hpc.ucalgary.ca:~/apps

1.1.13 ExploreDTI

On the remote computer.

cd ~/apps/matlab
mkdir ExploreDTI && cd ExploreDTI
wget http://www.exploredti.com/ExploreDTI/Pcode/ExploreDTI_Pcode.zip
unzip ExploreDTI_Pcode.zip && rm ExploreDTI_Pcode.zip

1.2 Local Mac Computer

These programs will be installed on your local computer, macOS. I am currently running macOS Mojave.

1.2.1 ACPCDETECT

mkdir ~/build
mkdir ~/apps

Download version 2 of the acpcdect on your local computer. Follow the link to download the program. Upload the file to your remote computer.

mv ~/Downloads/acpcdetect_V2.0_macOS10.12.6.tar ~/build/

On the remote computer, unzip the program.

mkdir -p ~/apps/acpcdetect
cd ~/build/
tar xvf acpcdetect_V2.0_macOS10.12.6.tar -C ~/apps/acpcdetect/

Using your preferred Terminal text editor, add these lines to your .bash_profile.

# ACPCDETECT
export ARTHOME=/Users/naomihunsaker/apps/acpcdetect
PATH=$ARTHOME/bin:$PATH

1.2.2 DCM2NIIX

We will build from source. If you have homebrew installed make sure you have the dependencies.

brew install cmake pkg-config

Then we will compile from source.

cd ~/build/
git clone https://github.com/rordenlab/dcm2niix.git
mkdir -p ~/apps/dcm2niix
cd ~/apps/dcm2niix
cmake ../../build/dcm2niix
make

You will need to add the following to your .bash_profile.

# DCM2NIIX
export PATH="/Users/ashleyware/apps/dcm2niix/bin:$PATH"

1.2.3 Quicklook Plugin

This plugin uses the Mac OS X Leopard’s built-in innovative Quick Look framework to enable a quick assessment of any 3-dimensional image volume in the supported medical image formats directly from the Finder. Using the Finder’s Cover Flow mode, a large collection of medical images can be browsed through and quickly inspected just as easy as flipping through your photos. Furthermore, a large number of images can be compared side-by side by selecting them together in the Finder, then pressing the space bar to bring up the Quick Look preview mode.

For more information: http://dti-tk.sourceforge.net/pmwiki/pmwiki.php?n=QuicklookPlugin.Main

1.2.7 ImageMagick

You should have already installed Homebrew when creating the Mindboggle singularity image. If you haven’t installed Homebrew yet, do so now.

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Once homebrew is installed, install ImageMagick.

brew install imagemagick

1.2.8 Statistical Parametric Mapping (SPM)

mkdir -p ~/apps/matlab/
cd ~/apps/matlab
wget http://www.fil.ion.ucl.ac.uk/spm/download/restricted/contradistinction/spm5.zip
unzip spm5.zip && rm spm5.zip
wget http://www.fil.ion.ucl.ac.uk/spm/download/restricted/idyll/spm8.zip
unzip spm8.zip && rm spm8.zip

1.2.9 VistaSoft