04 Dependencies Guides - LICE-dev/swane GitHub Wiki
Below some brief guides to help the User to install all the mandatory and optional dependencies of SWANe.
Important
Each one of these dependencies are free and some of them are open-source.
That means that there is rarely an assistance service to resolve the issues that can occur using the software.
By the way it's always possible to find help and clarifications on the websites, official documentation and forums of the dependencies developing communities.
Python is an interpreted, object-oriented, high-level programming language with dynamic semantics.
It is the main dependency of SWANe, required from both SWANe software and most of its direct dependencies that simply can't be executed without it.
Before trying to install Python3, check your Python Version in a terminal window, launching the following command:
python3 --version
Python 3.9.6
If Python3 is missing or its version is < 3.7, install Python 3.10 following the instructions below:
sudo apt update
sudo apt install python3.10 python3-pip
Python 3.9.6
Download the installer from this link and launch it.
PIP is the most common package installer for Python.
A lot of Python libraries and software, such as SWANe, are published on PIP.
Note
Usually, pip is automatically installed with Python, thus you won't need to install it manually.
After the installation of Python3, PIP can be installed following the official guide by launching the following command on terminal window:
python3 -m ensurepip --upgrade
Dcm2niix is designed to convert neuroimaging data from the DICOM format to the Nifti format.
Many scientific tools expect medical images to be stored in the Nifti format, much simpler than the DICOM format. That's why dcm2niix is one of the mandatory dependencies of SWANe.
On a terminal window launch the following command:
sudo apt install dcm2niix
On a terminal window launch the following command:
sudo port install dcm2niix
Note
The command above is using MacPorts (port command).
You can use another macOS package manager, but for this dependency we suggest that you use MacPorts.
Tip
If you have difficulty installing dcm2niix via MacPorts, you can download and execute the latest Mac Package Installer (.pkg file) from the official GitHub Releases webpage.
FSL is a comprehensive library of analysis tools for FMRI, MRI and DTI brain imaging data.
It's one of the mandatory dependencies of SWANe.
Warning
FSL is heavy software, the installation could take time.
Some of the oldest 6.0.5.X versions encounter issues with the Robust parameter of BET. To avoid them, please install the recommended FSL version (6.0.6).
Download the installer script from this link, open a terminal window and launch the following command:
cd ~/Downloads
python3 fslinstaller.py
Logout and login to start using FSL.
Download the installer script from this link, open a terminal-window and launch the following command:
cd ~/Downloads
python3 fslinstaller.py
Logout and login to start using FSL.
FreeSurfer is a software package for the analysis and visualization of structural and functional neuroimaging data from cross-sectional or longitudinal studies.
If FreeSurfer is available on your system, SWANe can run recon-all cortical reconstruction process.
Download the right version from this link and follow the configuration instructions below.
We recommend you to install FreeSurfer using the Tar Archive. Download Ubuntu tar archive from here, copy it in your home folder and extract it with the following commands (change the file name with your actual downloaded file):
cd $HOME
tar -v -zxpf freesurfer-linux-ubuntu22\_amd64-7.3.2.tar.gz
Remember to save the path configuration of FreeSurfer in your user terminal .profile.
Note
By default, the Ubuntu hidden profile file is $HOME/.profile. If you are using another shell, just apply these configurations in the relative profile configuration file.
Check this guide for further details.
Open it with a text editor (by default, macOS uses GNOME Text Editor) and follow the example below, replacing the path with your current FreeSurfer installation path. By default, it should be something like /home/freesurfer:
export FREESURFER\_HOME=$HOME/freesurfer
source $FREESURFER\_HOME/SetUpFreeSurfer.sh
Warning
FreeSurfer configuration lines should be placed BEFORE FSL configuration lines.
Logout and login to start using FreeSurfer.
We recommend you to install FreeSurfer using the Mac Package Installer found here. Download and execute it.
Remember to save the path configuration of FreeSurfer in your user terminal profile.
Note
By default, the macOS hidden profile file is $HOME/.zprofile. If you are using another terminal, apply these configurations in the relative profile configuration file.
Check this guide for further details.
Open it with a text editor (by default, macOS uses Apple's TextEdit ) and follow the example below, replacing the path with your current FreeSurfer installation path (/Applications/freesurfer/{version-num} , where {version-num} is the installed version from the official guide):
export FREESURFER_HOME=/Applications/freesurfer/{version-num}
source $FREESURFER_HOME/SetUpFreeSurfer.sh
Warning
FreeSurfer configuration lines should be placed BEFORE FSL configuration lines.
The MATLAB Runtime is a standalone set of shared libraries that enables the execution of compiled MATLAB applications or components.
If Matlab Runtime is installed in your system, SWANe can execute FreeSurfer to produce an automated segmentation of the hippocampal substructures and the nuclei of the amygdala.
To check if MatlabRuntime is installed or get installation instructions, enter into the /freesurfer/bin folder and use this command on both Ubuntu and macOS:
./checkMCR.sh
The ./CheckMCR.sh bash file is executed by SWANe at its launch.
If the SWANe terminal window returns the following alert:
checkMCR.sh: Permission denied
it means that the bash file is not executable. You can set the execution permission on the file with the following command (from the /freesurfer/bin folder)
sudo chmod + checkMCR.sh
Important
If the command returns no output, MATLAB Runtime for FreeSurfer is installed, otherwise the output will suggest the command to install the dependency.
For example:
ERROR: cannot find Matlab 2019b runtime in location:
/home/your_username/freesurfer/freesurfer/MCRv97
It is looking for either:
bin/glnxa64/libmwlaunchermain.so (Linux 64b) or
bin/maci64/libmwlaunchermain.dylib (Mac 64b)
The hippocampal/amygdala and brainstem modules require the (free) Matlab runtime.
You will need to download the Matlab Compiler Runtime (MCR) for Matlab 2019b.
To do so, please run the following command (you might need root permissions):
fs_install_mcr R2019b
For further details, please visit https://surfer.nmr.mgh.harvard.edu/fswiki/MatlabRuntime
The fs_install_mcr installation file is stored in the /freesurfer/bin folder and it needs the executable permission to be executed.
Set the permission with the following command:
sudo chmod + ./fs\_install\_mcr
Then launch the following command
./fs\_install\_mcr 2019b
Important
You may need the root permission to execute the fs_install_mcr command. In that case, you may need to insert into the installing command the $FREESURFER_HOME local variable. Be sure to follow the instructions that will appear on your terminal window.
A known issue with FSL >= 6.0.6 can cause the error shown in the following screenshot.
To fix it, you can follow the instruction displayed in the alert window.
We recommend you to use the automatic error fixing option.
3D Slicer is a software for visualization, processing, segmentation, registration and analysis of medical, biomedical and other 3D images and meshes and for planning and navigating image-guided processes.
If Slicer is available, SWANe will export workflow outputs in a complete and ready-to-use multimodal scene and will generate 3D models for better visualization of analysis results.
Download the right version from this link, then follow the configuration instructions below.
Download and extract the Linux release (.tar.gz file). Execute Slicer from the application folder.
cd $HOME
tar -v -zxpf Slicer-5.2.2-linux-amd64.tar.gz
It may be necessary to install some additional packages depending on the Ubuntu version, launching these commands in a terminal window.
sudo apt install libpulse-dev libnss3 libglu1-mesa
sudo apt install --reinstall libxcb-xinerama0
Install the SlicerFreeSurfer Extension.
Warning
In some versions of 3D Slicer the Extension Manager seems to be bugged and does not allow searching for additional extensions. If you encounter a similar problem, just download the SlicerFreeSurfer Extension from the Slicer Extensions Manager and import it to your local 3D Slicer Extensions Manager.
Download and open the macOS release.
Drag the Slicer application (Slicer.app) to a location of your choice (usually the Applications folder).
Install the SlicerFreeSurfer Extension.
Graphviz is a graph visualization software for representing structural information as diagrams of abstract graphs and networks.
SWANe uses Graphviz to visualize the analysis workflows as flowcharts.
This dependency is optional.
Open a terminal window and launch the following command:
sudo apt install graphviz
Open a terminal window and launch the following command, based on the package manager you are using:
Homebrew
brew install graphviz
Port
sudo port install graphviz
Tip
Homebrew may encounter some compatibility issues. We recommend you to use Port for Graphviz installation.