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:

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:

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:

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:

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:

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.

  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:

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#