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

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

1 - Linux

Install neurocommand on Linux

Ways of using Neurocommand in Linux:

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

Requirements:

Required

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

For user-specific desktop menus in a shared Linux environment

mkdir -p $HOME/.config/menus
mkdir -p $HOME/.local/share/applications
mkdir -p $HOME/.local/share/desktop-directories
ln -sfn /PATH_TO_YOUR_INSTALLATION/neurocommand/local/xfce-applications.menu $HOME/.config/menus
ln -sfn /PATH_TO_YOUR_INSTALLATION/neurocommand/local/neurodesk-applications.menu $HOME/.config/menus
ln -sfn /PATH_TO_YOUR_INSTALLATION/neurocommand/local/applications $HOME/.local/share/applications/neurodesk
ln -sfn /PATH_TO_YOUR_INSTALLATION/neurocommand/local/desktop-directories $HOME/.local/share/desktop-directories/neurodesk

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

  1. 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
  2. sudo apt-get install lxde to install LXDE desktop in WSL
  3. Reboot
  4. sudo apt-get install xrdp to install XRDP in WSL
  5. Open /etc/xrdp/xrdp.ini Change port=3389 to port=3390 and save
  6. Run echo startlxde > ~/.xsession

Running

  1. sudo service xrdp start to start xrdp server
  2. Open Microsoft Remote Desktop Connection in Windows host
  3. Connect to localhost:3390
  4. In the next login page, leave Session as Xorg. Enter your WSL username and password and click OK
  5. 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:

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

Requirements:

Required for installation

Required for use

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
# Note: Some HPCs install singularity/apptainer on the compute nodes directly (e.g. Bunya at UQ), so you don't need to do this step then.
  • 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`)!). It is recommended to perform this setup in a Python venv or conda environment:
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
# OR
export APPTAINER_BINDPATH=$PWD

Install Containers

  • If these steps are successful, the help will be displayed
  • Install all or only specific containers by following the instructions, e.g.:

To search for containers that have “itksnap” in the name:

bash containers.sh itksnap

Then you can copy and paste the specific install command or you can install all containers with that name:

bash containers.sh --itksnap

To download all containers (be careful - there are a lot of containers!):

bash containers.sh --all

Adding your containers to lmod

  • To add each container to the 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 it works. 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 also set the SINGULARITY_BINDPATH or the APPTAINER_BINDPATH variable in your .bashrc. This variable must contain a comma-separated list of directories you want to access with the Neurodesk tools.

e.g.:

export SINGULARITY_BINDPATH=/scratch/,/data/
export APPTAINER_BINDPATH=/scratch/,/data/
#Note: User the correct line depending on your installation. Do not add a directory that does not exist, otherwise the containers will not start!
  • 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 --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 --cli
  • 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 $@

or run this to update all containers

bash containers.sh --all

Example clusters

UQ Bunya

Neurodesk is already installed at UQ’s Bunya supercomputer. To access neurodesk tools you need to be in an interactive job (so either start a virtual desktop via Open On-Demand: https://bunya-ondemand.rcc.uq.edu.au/pun/sys/dashboard) or run:

salloc --nodes=1 --ntasks-per-node=1 --cpus-per-task=1 --mem=5G --job-name=TinyInteractive --time=01:00:00 --partition=debug --account=REPLACE_THIS_WITH_YOUR_AccountString srun --export=PATH,TERM,HOME,LANG --pty /bin/bash -l

Then load the neurodesk modules:

module use /sw/local/rocky8/noarch/neuro/software/neurocommand/local/containers/modules/
export APPTAINER_BINDPATH=/scratch,/QRISdata

Now you can list all modules (Neurodesk modules are the first ones in the list):

ml av

Or you can module load any tool you need:

ml qsmxt/6.4.1

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:

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:

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

  2. Select Remote-Containers: Open Container Configuration File from the dropdown panel

  3. This will open a neurodesktop%3alatest.json file. Overwrite the file with the following contents

{
	"workspaceFolder": "/home/user",
	"remoteUser": "jovyan"
}
  1. 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: image