Skip to content

Third-party software

Environment variables set-up

As you will see on this page, environment variables are often needed in order to configure some third-party software installations.

  1. Run the provided export and source commands in your terminal. Environment variables will be defined only for the duration of your session, and will be lost if you re-launch your terminal.

    Learn how to set environment variables
    • export var_name = value : defines an environment variable as value and makes it accessible to other processes started from the terminal.
    • source file : used to read/execute a file, for example one where configurations are set

  2. In order to define these variables permanently, you need to manually edit the configuration file associated to your shell.

    If you are using bash, it can be ~/.bashrc or ~/.bash_profile, if you are using zsh, it should be ~/.zshrc.

Provided command lines should be adapted

Please do not copy/paste the provided commands without adapting them to your system and without testing them. Most paths provided here require to be adapted to your system and depend on how you installed the software.

A good approach is to verify that the different paths you want to assign to a variable exist first :

→ If they do, then try running the export and source (step 1. above) commands in your terminal. Verify that the software or the pipeline you want runs as expected.

→ If this works, then consider modifying your shell configuration file (step 2. above) to have these variables automatically defined on every session.

Converters

Some converters require dcm2niix to transform DICOM files into NIfTI :

adni-to-bids aibl-to-bids genfi-to-bids nifd-to-bids ukb-to-bids

DCM2NIX

Version required

Clinica requires dcm2niix version 1.0.20230411 or later.

Please check the installation instructions for all platforms on dcm2niix Git repository.

Pipelines

Some, but not all pipelines use specific third-party software. Depending on your usage of Clinica, you will need to install additional packages. Specific dependencies are described in the table below (1) :

  1. If not listed, the pipeline does not require any additional dependency outside Clinica.
Clinica available pipelines
ANTs Convert3D FreeSurfer FSL ITK Matlab MRtrix3 PETPVC SPM
Anat > Linear ✓∘
Anat > Volume ✓ ✓
Anat > FreeSurfer ✓
DWI > Preprocessing ✓ ✓ ✓ ✓
DWI > DTI ✓ ✓ ✓
DWI > Connectome ✓ ✓ ✓
PET > Linear ✓
PET > Surface ✓ ✓ ✓⟡ ✓ ✓⟡ ✓
PET > Volume ✓⟡ ✓ ✓⟡ ✓
Stats > Surface ✓
Stats > Volume ✓ ✓
  • ✓∘ : for anatomical linear pipelines there is also the possibility to use ANTsPy instead of ANTs since Clinica v0.9.0
  • ✓⟡ : you only need to install ITK if you plan to perform partial volume correction using PETPVC.
CAT12 toolbox and Clinica < v0.3.7

Starting from Clinica v0.3.7, the CAT12 toolbox is no longer needed for the t1-volume and pet-volume pipelines. For previous versions of Clinica, you will need to download the latest version of the toolbox here and follow the instructions to ensure that your cat12 folder is located in your spm/toolbox folder.

Depending on the architecture and OS of your system, setup of third party libraries can change. Please refer to each tool’s website for installation instructions :

ANTs

To install ANTs, download it from ANTs release list and follow the instructions on ANTs wiki.

We strongly recommend installing ANTs >= 2.5.0 from which no environment variable are needed.

Nonetheless, if you are using an older version of ANTs, make sure to have the following environment variables defined:

export ANTSPATH="/path/to/your/ANTs/"
export PATH=${ANTSPATH}:${PATH}

Convert3D

You can find more details about Convert3D on their website. There are two options to install it :

FreeSurfer

You can find more details about FreeSurfer on their website. To install it :

Download and install FreeSurfer following the instructions on the wiki.

Warning

Please note that on Ubuntu you will need to install the packages tcsh and libjpeg62 ( a sudo apt-get install tcsh libjpeg62 should do the job).

Download it from here and follow the instructions on the FreeSurfer wiki.

Make sure to have the following environment variables defined:

export FREESURFER_HOME="/Applications/freesurfer"
source ${FREESURFER_HOME}/SetUpFreeSurfer.sh &> /dev/null

FSL

We recommend installing FSL 6.0.

Download it from here and follow the instructions on the FSL wiki.

Make sure to have the following environment variables defined: 

export FSLDIR="/usr/share/fsl/6.0"
export PATH="${FSLDIR}/bin":${PATH}
source ${FSLDIR}/etc/fslconf/fsl.sh

Download it from here and follow the instructions on the FSL wiki.

Make sure to have the following environment variables defined: 

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

ITK

You can find more details about ITK on their website. To install it :

Follow the instructions on the ITK blog.

Follow the instructions on the ITK blog.

MRtrix3

You can find more details about MRtrix3 on their website, including official instructions for downloading.

You have basically two options:

Tip

Note that using the conda package should be easier in most cases.

Matlab

You can find more details about Matlab on their website.

Warning

Note that using Matlab requires having a valid license which might be available through your university or institution.

Make sure to have the following environment variables defined:

export MATLAB_HOME="/path/to/your/matlab/bin/"
export PATH=${MATLAB_HOME}:${PATH}
export MATLABCMD="${MATLAB_HOME}/matlab"

PETPVC

You can find more details about PETPVC on their website, including official instructions for downloading on their Github.

You have basically three options:

Tip

If building from source, do not forget to compile in RELEASE mode, otherwise, partial volume correction will be very slow.

SPM12

SPM12 and Matlab

Note that SPM12 works with Matlab such that Clinica pipelines which require SPM12, will also need a Matlab installation. If you cannot install Matlab, you can install SPM standalone.

You can find more details about SPM12 on their website. To install it :

Download the latest version here and follow the instructions on the SPM wiki.

Download the latest version here and follow the instructions on the SPM wiki.

MacOS Big Sur

For systems running on MacOS Big Sur, a development version of SPM12 as well as a more recent release of the MCR (minimum 2019a) are required.

Then :

  1. Make sure to have the following environment variable defined: 

    export SPM_HOME="/path/to/your/spm12"

  2. You must also add SPM to the MATLAB path variable if you installed it as a toolbox.

    • First, verify a startup.m file exists in your initial working folder, by default ~/Documents/MATLAB (see here for more details). If the file does not exist, you can create it.
    • Then, type inside: 
      addpath('/path/to/your/spm12');
      OR, assuming the $SPM_HOME environment variable is set in your ~/.bashrc file : 
      [~, spmhome] = system('source ~/.bashrc > /dev/null; echo $SPM_HOME;');
spmhome = strsplit(spmhome,'\n');
addpath(spmhome{end-1});

    Warning

    zsh shell users will have to replace ~/.bashrc by ~/.zshrc.

SPM12 standalone

If you want to install SPM12 without installing Matlab, you will need to install two things:

  • The Matlab runtime (often abbreviated into MCR), for which no license is required.
  • The SPM standalone itself.

You can find details on how to install these on this page.

Verify your environment variables

If you followed the installation instructions, you should have set the environment variable $LD_LIBRARY_PATH.

In addition, you need to define the following environment variables:

export MCR_HOME="/path/to/your/MCR/"
export SPMSTANDALONE_HOME="/path/to/your/spmstandalone/home/"

Autocompletion (optional)

eval "$(register-python-argcomplete clinica)"

Autocompletion for zsh shell users

zsh shell users will have to add this right before the last line of their configuration file to enable autocompletion in Clinica:

autoload bashcompinit
bashcompinit
source ~/.bash_completion.d/python-argcomplete.sh

⚠️ Known issue with Matlab and SPM12

Matlab and SPM12 (whose implementation is based on Matlab) can sometimes randomly crash, causing a rather unreadable error in the console. Those events are unpredictable. In case it occurs to you, please do the following:

  • Check that you have a valid Matlab license.
  • Before relaunching the command line, be sure to remove the content of the working directory (if you specified one).

Contact us !