This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Neurocommand

For more advanced users who prefer a command-line interface

1: Linux
2: Windows
3: HPC
4: Visual Studio Code

Neurocommand requires a Linux host machine, virtual machine or WSL for Windows.

1 - Linux

Install neurocommand on Linux

Ways of using Neurocommand in Linux:

You can use the module files for Neurocontainers directly via CVMFS: https://www.neurodesk.org/docs/getting-started/neurocontainers/cvmfs/
or you can install Neurocommand as described here:

Requirements:

Required

python 3.6+ https://docs.conda.io/en/latest/miniconda.html#linux-installers
singularity https://docs.sylabs.io/guides/3.5/user-guide/quick_start.html
git

Optional

lmod https://lmod.readthedocs.io/en/latest/

command line mode (e.g. running on an HPC or CVL)

Load singularity and for best performance it should be 3.x e.g. module load singularity/3.5.0
Load or install aria2 to optimize the download performance of our containers e.g. module load aria2c
Run git clone https://github.com/NeuroDesk/neurocommand.git to clone the repository - make sure to clone this to a directory with enough storage, write permissions and NOT a symbolic link (to be sure run cd `pwd -P`)!
Run cd neurocommand to change into the directory
Run pip3 install -r neurodesk/requirements.txt --user to install pre-requisite python packages
Run bash build.sh --cli to install in cli mode
Run bash containers.sh for installing individual containers or bash containers.sh --all for installing all containers
Run module use $PWD/local/containers/modules/ to add the containers to your module search path. Add this to your .bashrc if working. When adding to your .bashrc you will need to replace $PWD to point to the correct path, i.e. module use ~/neurocommand/local/containers/modules/.
Run ml avail to see the installed containers at the top of the list (neurodesk containers will take preference over system modules with the same name). - If a container is not yet there run ml --ignore_cache avail
Every time you start a new shell you need to run module use PathToYourContainers or add this command to you .bashrc file.

GPU support

Some of our containers contain GPU-accelerated applications. Here is an example that runs the GPU accelerated program eddy in FSL:

module load fsl/6.0.5.1
export neurodesk_singularity_opts='--nv'
eddy_cuda9.1

For Lxde desktops

If running on an lxde desktop… Run bash build.sh --lxde --edit

For Mate desktops

Run bash build.sh --init (or bash build.sh --lxde --edit)
lxde/mate: Mate
installdir: Where all the neurocommand files will be stored (Default: ./local)
appmenu: The linux menu xml file. (Usually /etc/xdg/menus/****-applications.menu)
appdir: Location for the .desktop files for this linux desktop (Usually /usr/share/applications)
deskdir: Location for the .directory files for this linux desktop (Typically /usr/share/desktop-directories)

For desktop menus:

sudo bash install.sh to install
Creates symlinks to menu files in installation dir

sudo bash uninstall.sh to uninstall
Removes symlinks

To update

Run git pull
Run bash build.sh # this updates the neurocommand but not the modules install.sh does not need to be run again to update containers go into the neurodesktop directory and run bash containers.sh Choose the module you want to update for example you want to update mrtrix3/3.0.2 module with the eddy_cuda fix: ~/neurocommand/local/fetch_containers.sh mrtrix3 3.0.2 20221108 mrview $@

To download all containers

Run bash containers.sh --all

2 - Windows

Install neurocommand on Windows

WSL (w/ Ubuntu + LXDE)

For more information on WSL: https://docs.microsoft.com/en-us/windows/wsl

Setting up

Setup WSL2 using the following instructions (Ubuntu 18.04 recommended)
https://docs.microsoft.com/en-us/windows/wsl/install-win10 Proceed until a Ubuntu bash shell is available from the Windows Host
Run the remaining commands in the Bash shell
sudo apt-get install lxde to install LXDE desktop in WSL
Reboot
sudo apt-get install xrdp to install XRDP in WSL
Open /etc/xrdp/xrdp.ini Change port=3389 to port=3390 and save
Run echo startlxde > ~/.xsession

Running

sudo service xrdp start to start xrdp server
Open Microsoft Remote Desktop Connection in Windows host
Connect to localhost:3390
In the next login page, leave Session as Xorg. Enter your WSL username and password and click OK
This should open an LXDE Linux Desktop environment. Follow Linux guide from here on

3 - HPC

Run neurodesktop in a high performance computing environment

Ways of using Neurocommand in Linux:

You can use Neurocontainers (i.e., download Singularity containers) directly via CVMFS: https://www.neurodesk.org/docs/getting-started/neurocontainers/cvmfs/
or you can install Neurocommand as described here:

Requirements:

Required

python 3.6+ https://docs.conda.io/en/latest/miniconda.html#linux-installers
singularity https://docs.sylabs.io/guides/3.5/user-guide/quick_start.html
git

Optional

lmod https://lmod.readthedocs.io/en/latest/

NB: Your HPC will likely have lmod and Singularity already installed - check with your sysadmin

Command line mode (e.g. running on an HPC or CVL)

Load singularity and for best performance it should be 3.x e.g.

module load singularity/3.5.0

Load or install aria2 to optimize the download performance of our containers (THIS IS OPTIONAL)

module load aria2c

To install the repository, run the following (make sure to clone this to a directory with enough storage, write permissions and NOT a symbolic link (to be sure run cd `pwd -P`)!)

git clone https://github.com/NeuroDesk/neurocommand.git 
cd neurocommand 
pip3 install -r neurodesk/requirements.txt --user 
bash build.sh --cli
bash containers.sh
export SINGULARITY_BINDPATH=$PWD
export APPTAINER_BINDPATH=$PWD

Containers

If these steps were successful, all Neurodesk containers will be listed
Copy and paste the line for your desired container(s)

Adding your containers to lmod

To add each container to module search path, run the following:

module use $PWD/local/containers/modules/

It may be a good idea to add this to your .bashrc if this is working. When adding to your .bashrc you will need to replace $PWD to point to the correct path, i.e.

module use ~/neurocommand/local/containers/modules/

It is very important to set the SINGULARITY_BINDPATH variable in your .bashrc as well. This variable needs to contain all directories you want to access with the Neurodesk tools:

e.g.:

export SINGULARITY_BINDPATH=/scratch/,/data/

to see the installed containers at the top of the list (neurodesk containers will take preference over system modules with the same name), run:

module load --ignore_cache avail

Starting a new shell

Every time you start a new shell you will need to run conda activate neurocommand. Unless you added it to your .bashrc, you will also need to run module use PathToYourContainers.

To update

Run

git pull
bash build.sh

this updates the neurocommand but not the modules
install.sh does not need to be run again to update containers go into the neurodesktop directory and run

bash containers.sh

Choose the module you want to update for example you want to update mrtrix3/3.0.2 module with the eddy_cuda fix:

~/neurocommand/local/fetch_containers.sh mrtrix3 3.0.2 20221108 mrview $@

To download all containers

Run

bash containers.sh --all

4 - Visual Studio Code

Guide connecting your VS Code environment to Neurodesktop

The following guide is for connecting to Neurodesktop using a VS Code installation running on your host machine.

Please see additional instructions below if Neurodesktop is running remotely (i.e. Cloud, HPC, VM)

Pre-requisites

Visual Studio Code (https://code.visualstudio.com) installed on your host. Standalone version should work fine

Install the following VS Code extensions:

Docker extension (Required)
Remote development extension pack. Includes the following extensions
- Remote - Containers (Required)
- Remote - WSL (For windows hosts)

Connecting to Neurodesktop

Open VS Code and open a Folder (File > Open Folder)

This can be any folder (e.g. home or project folder). VS Code runs into errors if no folder is opened.

Open the Command Palette (Ctrl+Shift+P).

Select Remote-Containers: Attach to Running Container from the dropdown panel

Start typing in ’neurodesktop. Select /neurodesktop from the list

This should open a VS Code Window connected to the neurodesktop as a Dev Container.

This may take about a minute if it is the first time you are connecting, as VS code has to install the VS Code server onto the container. Repeat connections should be faster.

First time connection

The first time connection will default to using neurodesktop root user. We want the default connection to be as the normal user to avoid permission issues. To check which user is being used, open the terminal in the neurodesktop VS Code instance and check if the user is user or root

Follow the following steps to configure your VS Code instance to connect to neurodesktop as normal user by default:

Open the Command Palette (Ctrl+Shift+P).
Select Remote-Containers: Open Container Configuration File from the dropdown panel
This will open a neurodesktop%3alatest.json file. Overwrite the file with the following contents

{
	"workspaceFolder": "/home/user",
	"remoteUser": "jovyan"
}

Close this VS Code window. Use steps in previous section to connect normally

Useful Additions

A plugin to view neuroimaging data inside VScode is also available: