# Installing from source and dependencies

## Installation of source code

**Step 1**: Clone all QuNex repositories and initiate submodules:

* Clone: `git clone https://gitlab.qunex.yale.edu/qunex/qunex.git`
* Initiate submodules from inside cloned repository folder: `git submodule init`
* Pull and update all submodules: `git pull --recurse-submodules && git submodule update --recursive`
* Update submodules to the latest commit on origin: `git submodule foreach git pull origin master`
* Switch all submodules to the master branch: `git submodule foreach git checkout master`

**Step 2**: Configure your OS environment. Set the environmental variables `TOOLS` and `QUNEXREPO`. For example, if QuNex is located at `/qunex_suite/qunex`, set `TOOLS=/qunex_suite/` and `QUNEXREPO=qunex`. The easiest way to do this is by adding the following lines to your `.bash_profile`:

``` bash
TOOLS=<path to the root of where the software is installed>
QUNEXREPO=<relative path to the QuNex folder within $TOOLS, e.g. 'qunex'>
export TOOLS QUNEXREPO
```

**Step 3**: Install all necessary external dependencies:

* Connectome Workbench (v1.4.2 or above; [https://www.humanconnectome.org/software/connectome-workbench](https://www.humanconnectome.org/software/connectome-workbench))
* FSL (v6.0.5 or above with GPU-enabled DWI tools; [https://fsl.fmrib.ox.ac.uk/fsl/fslwiki](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki))
* FreeSurfer (v6.0.0; [http://ftp.nmr.mgh.harvard.edu/pub/dist/freesurfer/6.0.0/](http://ftp.nmr.mgh.harvard.edu/pub/dist/freesurfer/6.0.0/))
* MATLAB (vR2017b or above with Signal Processing, Statistics and Machine Learning and Image Processing Toolbox; [https://www.mathworks.com/downloads/](https://www.mathworks.com/downloads/))
* or GNU Octave (v4.4.1 or above with Image 2.6.2, Control 3.1.0, Signal 1.3.2, Statistics 1.3.0 and nan 3.1.4 packages; [https://www.gnu.org/software/octave/download.html](https://www.gnu.org/software/octave/download.html))
* PALM: Permutation Analysis of Linear Models ([https://github.com/andersonwinkler/PALM](https://github.com/andersonwinkler/PALM))
* Python (v3.7 or above with numpy, scipy, nibabel matplotlib, seaborn, PyPDF2, pydicom; [https://www.python.org/downloads/](https://www.python.org/downloads/))
* Human Connectome Pipelines ([https://github.com/Washington-University/HCPpipelines](https://github.com/Washington-University/HCPpipelines))
* Gradunwarp for HCP Pipelines ([https://github.com/Washington-University/gradunwarp](https://github.com/Washington-University/gradunwarp))
* HCP ASL Pipelines ([https://github.com/physimals/hcp-asl](https://github.com/physimals/hcp-asl))
* R Statistical Environment with ggplot2 and filelock library ([https://www.r-project.org/](https://www.r-project.org/))
* dcm2niix (23-June-2017 release; [https://github.com/rordenlab/dcm2niix](https://github.com/rordenlab/dcm2niix))
* dicm2nii (version 2018.08.08; [https://github.com/xiangruili/dicm2nii](https://github.com/xiangruili/dicm2nii))
* pydicom (v1.1.0 or later; [https://pydicom.github.io](https://pydicom.github.io))

**Step 4**: Source the Qunex environment. The most convenient way is to make the OS automatically source it by adding the following line to `.bash_profile`:

``` bash
source $TOOLS/$QUNEXREPO/env/qunex_environment.sh
```

**Step 5**: Setup the external dependencies. External tools should be installed inside the `$TOOLS` folder:

* The `qunex_environment.sh` script automatically sets assumptions for dependency paths. These can be changed by the user.
* For more info on how to define specific QuNex dependencies paths run: `qunex --envsetup`.

## Updating the QuNex Suite from Source

* To update the main QuNex repository and all the submodules run:

``` bash
git pull
git submodule update --recursive --remote
```

* For this to work you need to have an active git account and read access to the main QuNex repository and all submodules.

## QuNex environment setup

All the listed packages have to be either available on the system level or installed in the `TOOLS` directory. Please review and edit `$TOOLS/$QUNEXREPO/env/qunex_environment.sh` to ensure that all the dependencies are configured correctly. Once configured, for a full report of the QuNex Suite installed environment the user can run the following from the command line:

``` bash
qunex_environment_status
```

The default locations expected by `$TOOLS/$QUNEXREPO/env/qunex_environment.sh` are listed below. A user can always change these manually after the environment script is run.

``` bash
  TOOLS                               --> The base folder for the dependency installation
  │ 
  ├── qunex                           --> Env. Variable => QUNEXREPO -- All QuNex Suite repositories (https://gitlab.qunex.yale.edu/qunex)
  │ 
  ├── env                             --> conda environments with python packages
  │   └── qunex                       --> Env. Variable => QUNEXENV
  │
  ├── HCP                             --> Human Connectome Pipelines Folder (https://github.com/Washington-University/HCPpipelines)
  │   ├── HCPpipelines                --> Env. Variable => HCPPIPEDIR
  │   └── hcp-asl                     --> HCP ASL pipelines
  │
  ├── dcm2niix                        --> dcm2niix conversion tool (https://github.com/rordenlab/dcm2niix)
  │   └── dcm2niix.                   --> Env. Variable => DCMNIIDIR
  │
  ├── dicm2nii                        --> dicm2nii conversion tool (https://github.com/xiangruili/dicm2nii)
  │   └── dicm2nii.                   --> Env. Variable => DICMNIIDIR
  │
  ├── freesurfer                      --> FreeSurfer (http://ftp.nmr.mgh.harvard.edu/pub/dist/freesurfer/6.0.0-HCP/)
  │   └── freesurfer-<VERSION>        --> Env. Variable => FREESURFER_HOME (v6.0 or later stable for all other data)
  │
  ├── fsl                             --> FSL (v6.0.3 or above with GPU-enabled DWI tools; https://fsl.fmrib.ox.ac.uk/fsl/fslwiki)
  │   ├── fsl-<VERSION>               --> FSL installation
  │   ├── fsl                         --> Link to FSL installation, env. Variable => FSLDIR
  │   └── fix.                        --> Env. Variable => FSL_FIXDIR (https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FIX/UserGuide)
  │
  ├── matlab                          --> MATLAB vR2017b or higher. If MATLAB is installed system-wide then a symlink is created here.
  │   ├── matlab-latest               --> Env. Variable => MATLABDIR
  │   └── matlab-latest/bin           --> Env. Variable => MATLABBINDIR
  │
  ├── miniconda                       --> Env. Variable => CONDADIR, miniconda2 for python environment management (https://conda.io/projects/conda/en/latest/user-guide/install/)
  │
  ├── octave                          --> Octave v.4.4.1 or higher. If Octave is installed system-wide then a symlink is created here
  │   ├── octave-<VERSION>            --> Octave installation
  │   ├── octave                      --> Env. Variable => OCTAVEDIR, link to Octave installation
  │   ├── octave/bin                  --> Env. Variable => OCTAVEBINDIR
  │   └── octavepkg                   --> Env. Variable => OCTAVEPKGDIR -- If Octave packages need manual deployment then the installed packages go here.
  │
  ├── palm                            --> PALM: Permutation Analysis of Linear Models (https://github.com/andersonwinkler/PALM)
  │   ├── palm-o                      --> Env. Variable => PALMDIR (If using Octave)
  │   └── palm-m                      --> Env. Variable => PALMDIR (If using MATLAB)
  │
  ├── R                               --> R Statistical computing environment
  │   └── R-<VERSION>                 --> Env. Variable => RDIR
  │
  ├── gradunwarp                      --> HCP version of gradunwarp (https://github.com/Washington-University/gradunwarp)
  │   ├── gradunwarp-<VERSION>        --> Gradunwarp installation
  │   └── gradunwarp                  --> Env. Variable => GRADUNWARPDIR, link to granduwarp installation
  │
  └── workbench/workbench-<VERSION>   --> Connectome Workbench (v1.0 or above; https://www.humanconnectome.org/software/connectome-workbench)
      └── workbench-<VERSION>         --> Workbench installation
      └── workbench                   --> Env. Variable = HCPWBDIR, link to Workbench installation

These defaults can be redefined if the above paths are declared as global variables in the .bash_profile profile after loading the QuNex environment.
```

## Additional installation notes

For the tools that require compilation and/or installation, make sure that you download them to the temporary folder and then install them
in the correct location. E.g. `gradunwarp` would be installed by:

``` bash
cd $TMP
git clone https://github.com/Washington-University/gradunwarp.git
cd gradunwarp
python setup.py install --prefix=$TOOLS/pylib/gradunwarp
```

## Instructions for installation of QuNex and external dependencies

* [Octave installation](Octave-Installation)
* [PALM installation](PALM-Installation)
* [Installation on macOS](MacOS-Installation)

```{toctree}
:hidden:

Octave-Installation
PALM-Installation
MacOS-Installation
```