SWANe is developed and optimized for Ubuntu > 20.XX.

Other Linux Distros with the required dependencies can run SWANe, but this guide will only cover the Distros specified above.

SWANe is developed and optimized for macOS > 12.5.XX.

SWANe uses the following Python Packages:

• networkx (<3.0)
• nipype (1.8.6)
• PySide6
• PySide6_VerticalQTabWidget (0.0.3)
• pydicom (3.0.1)
• configparser (7.1.0)
• psutil (6.0.0)
• swane_supplement (0.1.2)
• matplotlib (3.9.2)
• nibabel (5.3.0)
• packaging
• GPUtil (1.4.0)
• numpy (2.1.1)
• cryptography

Below the recommend software/package installation order to make sure SWANe works properly:

• Python
• Pip
• Dcm2niix
• FSL
• FreeSurfer
• Matlab Runtime for FreeSurfer
• 3D Slicer
• Graphviz
• SWANe

On a terminal launch the following command:

pip3 install swane --break-system-packages

During SWANe installation with pip, the following error may occur on hardware with Apple Silicon CPU:

pip3 install swane
[…]
error: metadata-generation-failed

To fix it, you can install Scipy manually with Homebrew before SWANe, using the following command:

brew install scipy

On a terminal window launch the following command:

python3 -m swane

After the installation of FreeSurfer, the following error may occur at SWANe launching:

$ /usr/local/freesurfer/bin/recon-all: /bin/tcsh: badinterpreter: No such file or directory

To solve it, launch the following installation command.

sudo apt install tcsh

On a terminal window launch the following command:

pip3 install --upgrade swane --break-system-packages

During the installation of SWANe you may encour in dependency conflicts, expecially if on your OS there are different python environments (for example if you've installed Anaconda). To avoid module conflict problems, we suggest you to consider the creation of a Python virtual environment for the execution of SWANe .

A Python virtual environment is a self-contained directory that allows you to maintain separate and isolated settings and dependencies for different Python projects. This ensures that each project can have its own versions of libraries and modules, without interfering with those required by other projects. By using a virtual environment, you can manage project-specific package installations independently of the global Python environment installed on your system.

The creation and the configuration of a virtual environment is quite simple. Just follow these steps:

• Open your terminal and deactivate all the previous already active virtual environments with the following command (or equivalent, based on your OS and python3 version):

deactivate

• Launch the virtual environment creation command. You can customize the virtual environment name as you wish:

python3 -m venv swane_env

• Activate the SWANe virtual environment. You will see a prefix at the beginning of your terminal command line containing the name of the activated virtual environment (in our example: swane_env):

source $HOME/swane_env/bin/activate

• Install SWANe inside the activated environment:

python3 -m pip install swane

• At the end of the use of SWANe you can deactivate its virtual environment:

deactivate

• OPTIONAL: you can create a quick bash script to activate the SWANe virtual environment and launch SWANe to speed up the process:

echo "#!/bin/bash" > run_swane.sh
echo "source $HOME/swane_env/bin/activate" >> run_swane.sh
echo "python3 -m swane" >> run_swane.sh
chmod +x run_swane.sh

To use all SWANE funcitionalities you need to install lot of different tools and some of them are marked as unsecure or third party. In order to allow them to be installed you should follow this steps:

• Open System Settings.

• Click Privacy & Security, scroll down, and click the Open Anyway button to confirm your intent to open or install the app.

• The warning prompt apper and, if you're absolutely sure that you want to open the app anyway, you can click Open.

• The app is now saved as an exception to your security settings, and you can open it in the future by double-clicking it, just as you can any authorized app.

For more information about privacy and security for macos please look at https://support.apple.com/en-us/102445

Conda is a a package and environment management system, widely used for Python and R.

Conda uses its own environment and its own python interpreter for the execution of packages and software, and it is often set as the default environment in the terminal window of the OS after its installation.

Currently, there is no SWANe version compatible with the Conda environment due to a known issue with FSL and some of its functions (e.g.: the BET function).

We're working on it, but in the meantime, to make sure SWANe can work properly, you can launch the SWANe installation command outside the Conda environment to execute it without using the Conda python interpreter.

To point the right Python interpreter, you can specify its full path in the installation and launch command of SWANe.

After the installation, you can also create a customized alias to make it easier to start SWANe.

libxml2 is a C library and a direct and mandatory dependency for a wide range of other libraries.

If the installation of SWANe fails because this library is not present in your OS, you can easily solve the issue by installing the lxml toolkit.

On a terminal window launch the following command:

sudo apt install python3-lxml

On a terminal window launch the following command:

sudo port install py27-lxml

If you haven't already done it, your OS will ask you to install Xcode.

OpenGL is a multiplatform utility for 2D and 3D graphic renderig.

The missing of some or all OpenGL packages will bring to an error like this:

qt.qpa.plugin could not load the Qt platform plugin "xcb" in "" even though it was found

On a terminal window launch the following command:

sudo apt-get install '^libxcb.*-dev' libx11-xcb-dev libglu1-mesa-dev libxrender-dev libxi-dev libxkbcommon-dev libxkbcommon-x11-dev

if the problem persists after the OpenGL packages installation, and the launch of SWANe returns an error like this:

qt.qpa.plugin: Could not load the Qt platform plugin "wayland" in "" even though it was found.

it's necessary tu update the .profile configuration, adding the following string:

export QT_QPA_PLATFORM=xcb

libxcb-cursor0 is a porting for Xlib functions. a C library and a direct and mandatory dependency for a wide range of other libraries.

Some of the Ubuntu versions may need the manual installation of this package.

On a terminal window launch the following command:

sudo apt install libxcb-cursor0

Some of the new Ubuntu installation may miss the locale setup, that brings to an error with FSL, as follows:

LC_ALL: cannot change locale (en_US.UTF-8)

To fix the issue generate and set the locale for your OS.

On a terminal window launch the following command:

sudo locale-gen en_US.UTF-8

Some of the new Ubuntu installation may miss the unzip utility, that brings to an error with the MATLAB Runtime installation through FreeSurfer.

./fs_install_mcr: line 62: unzip: command not found

To fix the issue just install the unzip utility

On a terminal window launch the following command:

sudo apt install unzip -y