Before you begin, ensure your Ubuntu packages are up-to-date by running:

sudo apt update
sudo apt upgrade

Since a specific version of Python is required for PyGAMMA as well as the MATLAB Python Engine, installing and managing different versions of Python via pyenv is recommended. Download pyenv from here. There are installation instructions on that link, but a summary is provided here for installing pyenv into a shared location.

1. First install required dependencies for compiling and installing Python.

sudo apt install -y build-essential libssl-dev zlib1g-dev libbz2-dev \
libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev \
xz-utils tk-dev libffi-dev liblzma-dev python-openssl git

2. Install pyenv into a shared location.

sudo mkdir /opt/pyenv/
cd /opt/pyenv/
sudo git clone https://github.com/pyenv/pyenv pyenv

If you encounter an error such as the following when cloning pyenv ...

error: RPC failed; curl 56 GnuTLS recv error (-24): Decryption has failed.
fatal: the remote end hung up unexpectedly
fatal: early EOF
fatal: index-pack failed

... it is a HTTP/HTTPS timeout issue involving either some large commit size, or a weak network. As a workaround run the following commands instead:

sudo git config --global core.compression 0
sudo git clone --depth 1 https://github.com/pyenv/pyenv pyenv
cd pyenv
sudo git fetch --depth=2147483647
sudo git pull --all

3. Add the following lines to the end of ~/.profile.

export PYENV_ROOT=/opt/pyenv/
export PATH="$PYENV_ROOT/bin:$PATH"
if command -v pyenv 1>/dev/null 2>&1; then
        eval "$(pyenv init - --no-rehash)"
fi

4. Add the following lines to the end of /root/.profile. You may need administrative priveleges to complete this action.

export PYENV_ROOT=/opt/pyenv/
export PATH="$PYENV_ROOT/bin:$PATH"
if command -v pyenv 1>/dev/null 2>&1; then
        eval "$(pyenv init -)"
fi

5. Add /opt/pyenv/shims and /opt/pyenv/bin to the secure_path variable in the /etc/sudoers file. You may need administrative priveleges to complete this action.

secure_path = /opt/pyenv/shims:/sbin:/bin:/usr/sbin:/usr/bin:/opt/pyenv/bin

Python 3.7.7 is required as PyGAMMA does not yet support Python 3.8. Python 2.7.18 is also required as the installation script for FSL does not yet support Python 3. To install both these versions of python on your Ubuntu machine, use the following commands:

sudo -i pyenv install -v 3.7.7
sudo -i pyenv install -v 2.7.18

To set the default version of Python to be 3.7.7 on your machine, type:

sudo -i pyenv global 3.7.7

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 in subsequent instructions.

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 in subsequent instructions.
2. Navigate to that folder in a Terminal window (cd ) and clone the MAGIQ repository:

git clone https://github.com/dwong263/MAGIQ

Set the local python environment to version 3.7.7.

cd <Software Folder>/MAGIQ
pyenv local 3.7.7

1. Install PyQt5.

sudo apt install -y qtchooser libxcb-icccm4-dev libxcb-image0-dev libxcb-keysyms1-dev \
libxcb-render-util0-dev libxcb-xfixes0-dev libxcb-xinerama0-dev libxcb-xkb-dev \
libxkbcommon-x11-dev

sudo pip install PyQt5

2. Install scipy and numpy.

sudo pip install scipy

3. Install matplotlib.

sudo pip install matplotlib

4. Install pyfftw.

sudo pip install pyfftw

5. Install NiBabel.

sudo pip install nibabel

6. Install future.

sudo pip install future

1. From the L3Harris Geospatial Download and License Center, download the command line installer for Linux (IDL 8.7.3 for Linux (command line installer)).
2. In a terminal window, navigate to the download folder, extract the archive, and run the installation script.

tar -xzvf idl873-linux.tar.gz
sudo bash install.sh

3. Follow the prompts to install IDL.

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.

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

First, open a terminal window and navigate to <Software Folder>/MAGIQ/dep. Set the local pyenv environment to Python version 2.7.18.

pyenv local 2.7.18

This is necessary as the FSL installation script requires Python 2.7 to run properly. A "custom" version of this installation script is provided with MAGIQ. This is because the default FSL installation script does not detect the operating system correctly. Use the following instructions to run the script:

1. Install distro so the operating system is detected correctly.

pip2 install distro

2. Run the installer. sudo or administrative priveleges may be required for this operation.

python fslinstaller.py

Next, configure your shell by editing ~/.profile.

1. Change to your home directory and open the .profile file using VIM.

cd ~
vim .profile

2. Hit "i" on your keyboard to enter insert mode.
3. Add the following to the end of the file:

FSLDIR=/usr/local/fsl 
. ${FSLDIR}/etc/fslconf/fsl.sh 
PATH=${FSLDIR}/bin:${PATH} 
export FSLDIR PATH

4. Save the file by hitting the "Esc" key on your keyboard. Then type :x and hit "Enter".

1. Open a new Ubuntu 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.3.

PyGAMMA is a library for simulating spectra. We will need to build PyGAMMA for Python 3.7.7. If you installed all of the required dependencies for compiling and installing Python as detailed above, you should have everything you need to compile and build PyGAMMA.

To obtain the PyGAMMA code you'll need subversion. Install using the following command:

sudo apt install subversion

Once you have subversion, go to your <Software Folder>, and enter the following command:

svn co http://scion.duhs.duke.edu/guest_svn/gamma/trunk gamma

Next, change to the <Software Folder>/gamma/platforms/Linux directory. Then, execute this command:

make pysgdist

This builds PyGAMMA and places the relevant build output files in a place where setup.py can find them. When this process completes, you can install PyGAMMA.

Install PyGAMMA by navigating to the <Software Folder>/gamma/pygamma folder and running the command:

sudo python setup.py install

Fixing a PyGAMMA Install/Compile Bug

It seems that PyGAMMA built under Python 3.7.7 cannot be imported successfully from an *.egg file. To fix this:

1. Make a new directory called pygamma in /opt/pyenv/versions/3.7.7/lib/python3.7/site-packages.
2. Copy all files from <Software Folder>/gamma/pygamma/dist_staging into the directory you just created.
3. Delete the egg file (pygamma-4.3.4rc1-py3.7.egg) in /opt/pyenv/versions/3.7.7/lib/python3.7/site-packages.

Your installation is now complete! Open a new command prompt window and navigate to the folder containing the MAGIQ files and launch the program with the following commands:

cd /mnt/c/Users/<username>/Software/MAGIQ
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

You can also run the "Rodent Version" of BARSTOOL using the command:

python barstoolrv.py

Note that 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.

1. Download and install MATLAB.
2. In a command prompt window, execute the following commands. You may need sudo or administrative privileges to do this.

cd <MATLAB Root Folder>/extern/engines/python
sudo python setup.py install

3. Ensure you have the MATLAB NIFTI tools downloaded and on your MATLAB path.