For an overview of the Neurodesk platform, go to: Overview
Quick Start
To install the Neurodesktop container, go to: Getting Started
Feedback & Inquiries
To ask questions or suggest new features, join the discussion on github. For issues with the Neurodesk platform, please open a new issue.
Acknowledgments
Funding
Thank you to Oracle for Research for providing Oracle Cloud credits and related resources to support this project.
This project is supported by an Australian Research Data Commons (ARDC) Platform project “Australian
Electrophysiology Data Analytics PlaTform (AEDAPT)”.
License
MIT License
Copyright (c) 2021 NeuroDesk
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the “Software”), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
1 - Neurodesk Overview
A flexible, scalable and easy to use data analysis environment for reproducible neuroimaging.
What is Neurodesk?
Neurodesk provides a containerised data analysis environment to facilitate reproducible analysis of neuroimaging data. At Neurodesk, we believe that reproducibility should be a fundamental principle underlying neuroscientific data analysis (1). Analysis pipelines for neuroimaging data typically rely on specific versions of packages and software, and are dependent on their native operating system. These dependencies mean that a working analysis pipeline may fail or produce different results on a new computer, or even on the same computer after a software update. Neurodesk provides a platform in which anyone, anywhere, using any computer can reproduce your original research findings given the original data and analysis code.
What is a container?
The Neurodesk environment allows users to build and use containers for analysing neuroimaging data. Containers can be compared to virtual machines, in that they allow users to create a virtual, isolated computing environment with an operating system separate to that of the host machine. However, containers differ from virtual machines in that they virtualise software rather than hardware. Practically, this means that container images require few system resources to install, start-up quickly, and are easily portable between computers.
We recommend watching this excellent short video from the Australian Research Data Commons (ARDC) on research applications of software containers.
To read more about Docker containers, visit the Docker webpage
Video tutorial
Click here to watch a 2 minute introduction to the Neurodesk platform
National Academies of Sciences, Engineering, and Medicine. 2019. Reproducibility and Replicability in Science. Washington, DC: The National Academies Press. https://doi.org/10.17226/25303.
1.1 - How to cite us
How should I cite the tools I am using and Neurodesk itself?
Citing tools
We recommend to cite the tool you are using with the version number and the builddate, because this guarantees full reproducibility. You can find this information here: https://www.neurodesk.org/docs/overview/applications/. It’s also very important to cite the paper of the tool you are using and you find this information in the README.m of each tool, which you can find here (https://github.com/NeuroDesk/neurocontainers/tree/master/recipes) or when opening the application through the menu in Neurodesktop.
If you used any EEG/MEG or electrophysiology tools, please link to the AEDAPT website: https://www.aedapt.net/
Examples
“TGV QSM (v1.0.0_20210629, Langkammer, C; Bredies, K; Poser, BA; Barth, M; Reishofer, G; Fan, AP; Bilgic, B; Fazekas, F; Mainero; C; Ropele, S. Fast Quantitative Susceptibility Mapping using 3D EPI and Total Generalized Variation. Neuroimage. 2015 May 1;111:622-30. doi: 10.1016/j.neuroimage.2015.02.041) was run in Neurodesk (v20220302, https://www.neurodesk.org) (Renton, Angela I., Thanh Thuy Dao, David F. Abbott, Saskia Bollmann, Megan E. J. Campbell, Jeryn Chang, Thomas G. Close, et al. “Neurodesk: An Accessible, Flexible, and Portable Data Analysis Environment for Reproducible Neuroimaging.” bioRxiv, December 23, 2022. https://doi.org/10.1101/2022.12.23.521691)”
“EEGlab (2020.0_20211026, Delorme A & Makeig S (2004) EEGLAB: an open-source toolbox for analysis of single-trial EEG dynamics, Journal of Neuroscience Methods 134:9-21.) was run in Neurodesk (v20220302, https://www.neurodesk.org) part of the AEDAPT project https://www.aedapt.net/”
access to Neurocontainers via the Neurodesk menu (see list below)
If you can’t find an application in Neurodesktop’s menu, you may need to update Neurodesktop If you can’t find an application on the Nectar Desktop Service, visit our discussion forum to create a request For more information on data synchronization, visit our Storage section For guides and tutorials, refer to the respective tutorial
See below for a list of Neurocontainer applications available via the Neurodesk menu
1.3 - Release History
Previous releases of neurodesktop
Latest Version
20230531
20230525
fixed environment variables for nipype
fixed RDP upload permission errors
20221216
added VNC connection back into docker container because RDP currently causes issues for european keyboards
update for PhysIO toolbox (physiological noise correction for fMRI) to r2021a including the latest SPM r8224
update of lcmodel to include basis sets for 1.5-9.4T
added a memory display plugin to illustrate how much memory is available to the container and how much is consumed
added a version checker to help with identifying if a new version is available
added file upload via guacamole (+ update of guacamole to 1.4) - users can now drag and drop their files onto guacamole and they get copied to the desktop
20220128
update of Spinalcordtoolbox to 5.5
update of CAT12 to r1933
20220121
MNE Python 0.23.4 container including VScode and extensions
VScode container including Python/Julia Extensions and singularity to test “Inception Mode” (Running singularity containers within singularity containers)
update of fsl to 6.0.5.1
added CAT12 (a software that allows estimation of tissue volumes (and additional surface parameters such as cortical thickness, gyrification or fractal dimension) for different volume and surface-based atlas maps)
20220111
a deep learning based vessel segmentation algorithm “vesselapp” was added in version 0.3.1
palm - Permutation Analysis of Linear Models - was added in version alpha119
niistat running in octave was added with version 1.0.20191216
MRIcroGL was updated to a version with included python support, so the scripting is now working
rabies - Rodent Automated Bold Improvement of EPI Sequences was added with version 0.3.5
added more categories in applications menu (Body, Electrophysiology, Hippocampus, Phase Processing, Rodent Imaging, Shape Analysis, Spine, Statistics)
bugfix: improved startup time of the desktop container (miniconda in homedirectory was causing chmod slowdown)
bugfix: ssh, vnc and rdp servers are now restarted in case the container was stopped and started again (e.g. on Standby)
20210929
fixed naming of aidmri to aidamri and added new category “Rodent Imaging”
updated all tool icons and updated neurodesk icon including background image
VScode now stores settings in persistent storage /neurodesktop-storage and with this keeps extensions and settings across different neurodesktop versions
docker layers are now cached, so updating the desktop to the next version is very fast and consumes less disk space locally
default theme of terminal changed from Solarized to Tango as the old theme was hiding information in tools like htop (same font colour on same background…)
20210923
removed faulty mriqc 0.15.2 container
neurodesk.github.io is now starting page in firefox browser
20210918
added mriqc 0.16.1 and mrtrix 3.0.3
20210917
included more tools for connecting to cloud storage services (rclone, owncloud, nextcloud, davfs2, globus). For more info: Storage
styling of desktop interface, including background wallpaper and colour scheme in terminal window
new categories in menu system (visualization) and added more categories to tools
20210916
This is the first version of the newly renamed and rebuild neurodesktop (previously vnm and neuromachine)
containers are mounted by default from CVMFS, but this can be deactivated by adding -e CVMFS_DISABLE=true to the docker call
2 - Getting Started
Getting Started
Release
Ensure you note the release date of the Neurodesktop container image during installation, as it’s indicated in the docker run command, e.g.
We regularly update Neurodesktop for optimal performance and updated software. Check the Release History for past releases. To upgrade your container, replace the release number with your desired version. For replicable analysis pipelines, share the stable release number you used, enabling others to recreate your work environment anywhere.
Video tutorial
See below for a 14 minute tutorial video from eResearch 2021
2.1 - Neurodesktop
The plug-and-play, browser-accessible, containerised data analysis environment.
2.1.1 - Neurodesk App
Neurodesk App is the cross-platform desktop application for Neurodesk
Minimum System Requirements
At least 5GB free space for neurodesktop base image
Docker requirements.
Installing Docker
Neurodesk App requires Docker to be installed on your computer. If you already have Docker installed, you can skip this step.
After installation, open a terminal (Linux/macOS) or command prompt (Windows) and run the following command to verify that Docker is working correctly:
docker --version
docker run hello-world
Installing Neurodesk App
If you have an existing Neurodesk App installation, please uninstall it first by following the uninstall instructions.
Neurodesk App can be launched from the GUI of your operating system by clicking the application’s icon or by using neurodeskapp command from the command line.
Neurodesk App sets File Browser’s root directory based on the launch method.
If launched from the application icon on GUI or by using neurodeskapp command without any arguments, then the default working directory is set as the root directory. The default working directory is user home directory but it can be customized from the Settings dialog.
Sessions and Projects
Sessions represent local project launches and connections to existing Neurodesk servers. Each Neurodesk UI window in the app is associated with a separate session and sessions can be restored with the same configuration later on.
Session start options
You can start a new session by using the links at the Start section of the Welcome Page.
Open Local Neurodesk.. creates a new session in the default working directory.
Connect to remote Neurodesk server.. creates a session by connecting to a remote Neurodesk server.
Previously opened sessions are stored as part of application data and they are listed on the Welcome Page. Clicking an item in the Recent sessions list restores the selected session.
neurodeskapp command-line launch examples
Run neurodeskapp in the terminal.
Connecting to local Neurodesk
Neurodesk App creates new Neurodesk sessions by launching a locally running Neurodesk server and connecting to it. To open a local instance, click the Open Local Neurodesk.. button in the Start section of the Welcome Page.
It will show a Jupyterlab interface. There are two options to interact with Neurodesk:
By clicking the NeurodeskApp icon on the right. It launches new window to start Neurodesk interface.
By module loading containers on the left bar. You can interact with loaded modules in Terminal through command lines.
Connecting to a remote Neurodesk Server
It can also connect to an existing Neurodesk server instance that is running remotely. In order to connect to a server, click the Connect to remote Neurodesk server.. button in the Start section of the Welcome Page.
This will launch a dialog that automatically lists the remote Neurodesk server instances.
Select a server from the list or enter the URL of the Neurodesk application server. If the server requires a token for authentication, make sure to include it as a query parameter of the URL as well (/lab?token=<token-value>). After entering a URL hit Enter key to connect.
If the Persist session data option is checked, then the session information is stored and Neurodesk App will re-use this data on the next launch. If this option is not checked, the session data is automatically deleted at the next launch and servers requiring authentication will prompt for re-login.
You can delete the stored session data manually at any time by using the Clear History option in the Privacy tab of Settings dialog.
Configuration and data files
Neurodesk App stores data in ~/neurodesktop-storage for Linux and Mac, or C:/neurodesktop-storage for Windows, as default.
Add Custom Data Directory
Neurodesk App stores its data in the following locations:
By default, /home/jovyan/neurodesktop-storage in the app (which is binded with local directory ~/neurodesktop-storage in Unix or C:/neurodesktop-storage in Windows)
By choice, in the setting window below, select Additional Directory on the left side bar, click Change button to select the local directory, then click Apply & restart. The next time you start the app, the data from the local directory can be found in /home/jovyan/data.
Find the application installation NeurodeskApp.app in Finder (in /Applications or ~/Applications) and move to Trash by using CMD + Delete. Clean other application generated files using:
rm -rf ~/Library/neurodeskapp # to remove application cache
rm -rf ~/Library/Application\ Support/neurodeskapp # to remove user data
Windows
On Windows, go to Windows Apps & Features dialog using Start Menu -> Settings -> Apps and uninstall Neurodesk App as shown below.
In order to remove application cache, delete C:\Users\<username>\AppData\Roaming\neurodeskapp directory.
2.1.2 - Linux
Install neurodesktop on Linux
Minimum System Requirements
At least 3GB free space for neurodesktop base image
If you get errors in neurodesktop then check if the ~/neurodesktop-storage directory is writable to all users. Otherwise run:
chmod a+rwx ~/neurodesktop-storage
Once neurodesktop is downloaded, leave the terminal open and check the server neurodesktop running on (Avoid pressing CTRL+C). For example,
To access neurodesktop, open your web browser and type in one of those provided URLs provided in your terminal (e.g. http://127.0.0.1:8888/lab?token=your_unique_token).
If using Chrome, a pop-up may open with the text:
"http://127.0.0.1:8888 wants to
See text and images copied to the clipboard".
You should press “Allow”
If using Firefox, you might not be able to paste clipboard content into the virtual desktop from the host computer. In that case, please follow this instructions
Press on “Desktop Auto-Resolution” under “ALL CONNECTIONS”
If it is the first time you use Neurodesktop, wait until the desktop appears (it may take a few seconds). Otherwise, it should appear instantaneously.
Neurodesk is ready to use! Click “What’s next?” on the left of this page for further instructions.
The browser can be closed anytime, and Neurodesktop will continue running in the background. To reconnect to Neurodesktop, simply start over from step 3 above.
Deleting neurodesktop:
When done processing your data it is important to stop and remove the container - otherwise the next start or container update will give an error ("… The container name “/neurodesktop” is already in use…")
Note
Notice that any data that were saved outside of /neurodesktop-storage would be lost. Please make sure to move all your data to that folder before deleting neurodesktop.
Click on the terminal from which you ran neurodesktop
wget https://developer.download.nvidia.com/compute/cuda/11.5.0/local_installers/cuda_11.5.0_495.29.05_linux.run
sudo sh ./cuda_11.5.0_495.29.05_linux.run
Running tensorflow (w/ GPU)
Using tensorflow (python)
conda install tensorflow-gpu
python
import tensorflow as tf
print("Num GPUs Available: ", len(tf.config.list_physical_devices('GPU')))
Using tensorflow (singularity container in neurodesktop)
singularity pull docker://tensorflow/tensorflow:latest-gpu
singularity run --nv tensorflow_latest-gpu.sif
python
import tensorflow as tf
print("Num GPUs Available: ", len(tf.config.list_physical_devices('GPU')))
There is a bug in docker 3.3.0 for Mac that makes this command not run correctly and there will be no application menu when you start the desktop. Update your docker version when you see this!
if you get errors in neurodesktop then check if the ~/neurodesktop-storage directory is writable to all users, otherwise run chmod a+rwx ~/neurodesktop-storage
Once neurodesktop is downloaded, leave the terminal open and check the server neurodesktop running on (Avoid pressing CTRL+C). For example,
To access neurodesktop, open your web browser and type in one of those provided URLs provided in your terminal (e.g. http://127.0.0.1:8888/lab?token=your_unique_token).
We recommend to use Chrome over Firefox as it has an option to hide the Toolbar in full screen mode (go to the menu bar, click on View, and uncheck “Always Show Toolbar in Full Screen”). This allows for Neurodesktop to truly utilise the whole of your screen.
Press on “Desktop Auto-Resolution” under “ALL CONNECTIONS”
If it is the first time you use Neurodesktop, wait until the desktop appears (it may take a few seconds). Otherwise, it should appear instantaneously.
Neurodesk is ready to use! Click “What’s next?” on the left of this page for further instructions.
The browser can be closed anytime, and Neurodesktop will continue to run in the background. To reconnect to Neurodesktop, simply start over from step 3 above.
Deleting neurodesktop:
When done processing your data it is important to stop and remove the container - otherwise the next start or container update will give an error ("… The container name “/neurodesktop” is already in use…")
Note
Notice that any data that were saved outside of /neurodesktop-storage would be lost. Please make sure to move all your data to that folder before deleting neurodesktop.
Click on the terminal from which you ran neurodesktop
The docker installation will reboot your computer a few times and there might be warnings regarding WSL2 and this also might require a few more installation steps that unfortunately differ for every system. Please get in touch if you are stuck and have a look at our troubleshoot page.
Once neurodesktop is downloaded, leave the terminal open and check the server neurodesktop running on (Avoid pressing CTRL+C). For example,
To access neurodesktop, open your web browser and type in one of those provided URLs provided in your terminal (e.g. http://127.0.0.1:8888/lab?token=your_unique_token).
Note
We do not recommend the use of the Firefox browser for accessing Neurodesktop on Windows 10, as firefox is not able to access localhost where neurodesk is running.
Press on “Desktop Auto-Resolution” under “ALL CONNECTIONS”
If it is the first time you use Neurodesktop, wait until the desktop appears (it may take a few seconds). Otherwise, it should appear instantaneously.
Neurodesk is ready to use! Click “What’s next?” on the left of this page for further instructions.
The browser can be closed anytime, and Neurodesktop will continue running in the background. To reconnect to Neurodesktop, simply start over from step 3 above.
Deleting neurodesktop:
When done processing your data it is important to stop and remove the container - otherwise the next start or container update will give an error ("… The container name “/neurodesktop” is already in use…")
Note
Notice that any data that were saved outside of /neurodesktop-storage would be lost. Please make sure to move all your data to that folder before deleting neurodesktop.
Click on the terminal from which you ran neurodesktop
On the computer from which you want to access Neurodesktop, open an SSH connection to your cloud instance with port forwarding (USER should be substituted with a username that has admin privileges on the cloud instance, and IP should be substituted with the IP address of the cloud instance)
If you get errors in neurodesktop then check if the ~/neurodesktop-storage directory is writable to all users. Otherwise run:
chmod a+rwx ~/neurodesktop-storage
Once neurodesktop is downloaded, leave the terminal open and check the server neurodesktop running on (Avoid pressing CTRL+C). For example,
Even if your connection to the cloud instance is broken, and the terminal does not respond, Neurodesktop will still continue running on the cloud instance. When the connection to the cloud instance is re-established, please start over the instructions from step 3 below.
If it is required to set up an SSH tunnel to access the cloud instance, please set up such a tunnel from the computer from which you want to access Neurodesktop (e.g. ssh -L 8080:127.0.0.1:8080 USER@IP)
To access neurodesktop, open your web browser and type in one of those provided URLs provided in your terminal (e.g. http://127.0.0.1:8888/lab?token=your_unique_token)
The browser can be closed anytime, and Neurodesktop will continue running on the cloud instance. To reconnect to Neurodesktop, simply start over from step 4 above.
If your computer hibernates/reboots/etc. or if the network connection has been temporarily lost, Neurodesktop still continues running on the cloud instance. To reconnect to Neurodesktop, start over from step 3 above.
If you want to connect to the same instance of Neurodesktop from another computer, close the browser in the current computer, and start over from step 3 on the other computer (note that only one computer can access Neurodesktop at a time using the default RDP protocol; for access from multiple computers simultaneously, please re-run Neurodesktop with VNC enabled as explained further below).
Deleting neurodesktop:
When done processing your data it is important to stop and remove the container - otherwise the next start or container update will give an error ("… The container name “/neurodesktop” is already in use…")
Note
Notice that any data that were saved outside of /neurodesktop-storage would be lost. Please make sure to move all your data to that folder before deleting neurodesktop.
Click on the terminal from which you ran neurodesktop
You can also connect to this cloud instance from your iOS device :) For this install https://webssh.net/documentation/help/networking/port-forwarding/ and create a tunnel (the tool is free for one connection). Start the docker container in a screen session and then connect to it from your ios device in the browser.
You can upload data to the desktop by simply drag-and-dropping files on the browser window. Data uploaded during your session are stored on Oracle Cloud, and will be automatically deleted at the end of the session. To download your files before deletion: You need to open the guacamole settings by pressing CTRL-ALT-SHIFT (Control-Command-Shift on Mac). This will open a menu on the side:
where you can click on “Shared Drive”:
and a click (or double clink on Mac) on the file will start the download.
You can browse into folders in the shared drive by clicking (double clicking on Mac) on them. To get back to the base of the shared drive, press on the drive icon in the top left of the side menu (just below the “Shared Drive” title).
To close the side menu, click on CTRL-ALT-SHIFT once more (Control-Command-Shift on Mac).
2.2 - Neurocommand
For more advanced users who prefer a command-line interface
Neurocommand requires a Linux host machine, virtual machine or WSL for Windows.
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 will need to run conda activate neurocommand. Unless you added it to your .bashrc, you will also need to run module use PathToYourContainers.
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 $@
Setup WSL2 using the following instructions (Ubuntu 18.04 recommended) https://docs.microsoft.com/en-us/windows/wsl/install-win10Proceed 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
2.2.3 - HPC
Run neurodesktop in a high performance computing environment
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`)!)
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:
This will open a new VS Code instance connected to the remote host via SSH. You may close the previous VS Code instance.
Follow the steps in the next section using the new VS Code instance
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.
First time connection will take about a minute, as VS code has to install the VS Code server onto the container. Repeat connections should be faster
First time connection
First time connection will default to using neurodesktop root user. We want to default connection to be as the normal user to avoid permission issues.
To check which user is being use, open the terminal in the neurodesktop VS Code and check if the user is user or root
Follow the following steps to configure your VS Code 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
Once installed create the keys and configure the servers used:
sudo mkdir -p /etc/cvmfs/keys/ardc.edu.au/
echo "-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwUPEmxDp217SAtZxaBep
Bi2TQcLoh5AJ//HSIz68ypjOGFjwExGlHb95Frhu1SpcH5OASbV+jJ60oEBLi3sD
qA6rGYt9kVi90lWvEjQnhBkPb0uWcp1gNqQAUocybCzHvoiG3fUzAe259CrK09qR
pX8sZhgK3eHlfx4ycyMiIQeg66AHlgVCJ2fKa6fl1vnh6adJEPULmn6vZnevvUke
I6U1VcYTKm5dPMrOlY/fGimKlyWvivzVv1laa5TAR2Dt4CfdQncOz+rkXmWjLjkD
87WMiTgtKybsmMLb2yCGSgLSArlSWhbMA0MaZSzAwE9PJKCCMvTANo5644zc8jBe
NQIDAQAB
-----END PUBLIC KEY-----" | sudo tee /etc/cvmfs/keys/ardc.edu.au/neurodesk.ardc.edu.au.pub
echo "CVMFS_USE_GEOAPI=yes" | sudo tee /etc/cvmfs/config.d/neurodesk.ardc.edu.au.conf
echo 'CVMFS_SERVER_URL="http://cvmfs.neurodesk.org/cvmfs/@fqrn@;http://cvmfs-brisbane.neurodesk.org/cvmfs/@fqrn@;http://cvmfs-sydney.neurodesk.org/cvmfs/@fqrn@;http://cvmfs-frankfurt.neurodesk.org/cvmfs/@fqrn@;http://cvmfs-zurich.neurodesk.org/cvmfs/@fqrn@;http://cvmfs-toronto.neurodesk.org/cvmfs/@fqrn@;http://cvmfs-ashburn.neurodesk.org/cvmfs/@fqrn@;http://cvmfs.neurodesk.org/cvmfs/@fqrn@"' | sudo tee -a /etc/cvmfs/config.d/neurodesk.ardc.edu.au.conf
echo 'CVMFS_KEYS_DIR="/etc/cvmfs/keys/ardc.edu.au/"' | sudo tee -a /etc/cvmfs/config.d/neurodesk.ardc.edu.au.conf
echo "CVMFS_HTTP_PROXY=DIRECT" | sudo tee /etc/cvmfs/default.local
echo "CVMFS_QUOTA_LIMIT=5000" | sudo tee -a /etc/cvmfs/default.local
sudo cvmfs_config setup
For WSL users
It is required to run this for each new new WSL session:
sudo cvmfs_config wsl2_start
Test if the connection works:
sudo cvmfs_config chksetup
ls /cvmfs/neurodesk.ardc.edu.au
sudo cvmfs_talk -i neurodesk.ardc.edu.au host probe
sudo cvmfs_talk -i neurodesk.ardc.edu.au host info
cvmfs_config stat -v neurodesk.ardc.edu.au
For Ubuntu 22.04 users
If configuring CVMFS returns the following error:
Error: failed to load cvmfs library, tried: './libcvmfs_fuse3_stub.so' '/usr/lib/libcvmfs_fuse3_stub.so' '/usr/lib64/libcvmfs_fuse3_stub.so' './libcvmfs_fuse_stub.so' '/usr/lib/libcvmfs_fuse_stub.so' '/usr/lib64/libcvmfs_fuse_stub.so'
./libcvmfs_fuse3_stub.so: cannot open shared object file: No such file or directory
/usr/lib/libcvmfs_fuse3_stub.so: cannot open shared object file: No such file or directory
/usr/lib64/libcvmfs_fuse3_stub.so: cannot open shared object file: No such file or directory
./libcvmfs_fuse_stub.so: cannot open shared object file: No such file or directory
libcrypto.so.1.1: cannot open shared object file: No such file or directory
/usr/lib64/libcvmfs_fuse_stub.so: cannot open shared object file: No such file or directory
Failed to read CernVM-FS configuration
if [ -f '/usr/share/module.sh' ]; then source /usr/share/module.sh; fi
if [ -d /cvmfs/neurodesk.ardc.edu.au/neurodesk-modules ]; then
# export MODULEPATH="/cvmfs/neurodesk.ardc.edu.au/neurodesk-modules"
module use /cvmfs/neurodesk.ardc.edu.au/neurodesk-modules/*
else
export MODULEPATH="/neurodesktop-storage/containers/modules"
module use $MODULEPATH
export CVMFS_DISABLE=true
fi
if [ -f '/usr/share/module.sh' ]; then
echo 'Run "ml av" to see which tools are available - use "ml <tool>" to use them in this shell.'
if [ -v "$CVMFS_DISABLE" ]; then
if [ ! -d $MODULEPATH ]; then
echo 'Neurodesk tools not yet downloaded. Choose tools to install from the Application menu.'
fi
fi
fi
Restart the current shell or run
source ~/.bashrc
Use of containers in the module system
export SINGULARITY_BINDPATH='/cvmfs,/mnt,/home'
module use /cvmfs/neurodesk.ardc.edu.au/neurodesk-modules/*
ml fsl
fslmaths
2.3.2 - DataLad
Neurodesktop containers can be used in datalad container run
vi .datalad/config
# now change the version of the container you like
# all available containers can be seen via `ls images/neurodesk`
datalad save -m 'downgraded version of romeo to x.x.x'
datalad containers-run -n neurodesk-romeo
Option 2: change version using freeze_versions script
# all available containers can be seen via `ls images/neurodesk`
scripts/freeze_versions neurodesk-romeo=3.2.4
datalad save -m 'downgraded version of romeo to 3.2.4'
datalad containers-run -n neurodesk-romeo
The singularity containers can be also be used in combination with our Transparent Singularity Tool tool, that wraps the executables inside a container to make them easily available for pipelines. More information can be found here:
When restarting WSL the cvmfs service has to be started manually:
sudo cvmfs_config wsl2_start
Initialize the neurodesk modules:
module use /cvmfs/neurodesk.ardc.edu.au/neurodesk-modules/*
Example usage of fsleyes:
ml fsl
fsleyes
List the available programs:
ml av
2.4 - Storage
Add storage to Neurodesktop
Drag and Drop
Uploading files
You can drag-and-drop files into the browser window to get files into the Neurodesktop. This will then start a file upload:
Downloading files
To download files from the desktop using the same mechanism you need to open the guacamole settings by pressing CTRL-ALT-SHIFT (Control-Command-Shift on Mac). This will open a menu on the side:
where you can click on “Shared Drive”:
and a click (or double clink on Mac) on the file will start the download.
You can browse into folders in the shared drive by clicking (double clicking on Mac) on them. To get back to the base of the shared drive, press on the drive icon in the top left of the side menu (just below the “Shared Drive” title).
To close the side menu, click on CTRL-ALT-SHIFT once more (Control-Command-Shift on Mac).
Note that it’s only possible to download one file at the time through this interface. If you have multiple files in a directory we recommend opening a terminal and zipping the files and then downloading one zip archive:
zip files.zip files/
Local storage
If you are running Neurodesktop on your own hardware there will be a direct connection between the “Storage” folder on the Destkop, which is a link to “/neurodesktop-storage” and a “neurodesktop-storage” folder on your C-drive (Windows) or home directory (Mac/Linux). This connection can be used for data processing and data transfer.
Mounting external storage on your host-computer
The -v C:/neurodesktop-storage:/neurodesktop-storage part of the docker command links the directory “neurodesktop-storage” on the “C drive” of your Windows computer to the directory /neurodesktop-storage inside the Desktop environment. Everything you store in there will be available inside the desktop and on the host computer. You can also mount additional directories by adding another -v parameter set (e.g. -v D:/moredata:/data) - this will mount the directory moredata from your D drive to /data inside neurodesktop. Important: the mountpoint inside neurodesktop should be named /data (or anything from this list: https://github.com/NeuroDesk/neurocontainers/blob/master/recipes/globalMountPointList.txt) - otherwise most of the tools will not be able to access the data.
Here is an example for Windows adding another storage directory:
Another way to get your data into Neurodesktop is to use a cloud storage provider like CloudStor, Dropbox, OneDrive and their sync tools like OwnCloud, Nextcloud or very flexible tools like rclone or davfs2. Another good option could be to utilize Globus for large amounts of data.
Nextcloud and Owncloud desktop clients
Under the menu item “Accessories” you can find “Nextcloud” and “ownCloud” desktop sync clients that you can configure with your cloud service accounts.
To connect for example to your AARNET cloudstor account you can start the ownCloud client and enter the Server Address:
Enter the Password / Token from the CloudStor App passwords page and confirm it again:
Leave blank the bearer_token: <hit Enter>
No advanced config necessary: <hit Enter>
accept the configuration: <hit Enter>
Quit the config: q
Now we can download data to the HPC easily: rclone copy --progress --transfers 8 CloudStor:/raw-data-for-science-paper .
or upload data to CloudStor: rclone copy --progress --transfers 8 . CloudStor:/data-processed
Globus
We also provide the globus client, so you can transfer large amounts of data between globus endpoints and Neurodesktop. You can configure it by running:
ml globus
# First run the setup:
globusconnectpersonal -setup -nogui
# Then start the GUI:
globusconnectpersonal -gui
Once authenticated you can go to the globus file-manager https://app.globus.org/file-manager and your neurodesktop instance will be an endpoint for globus.
Mount volume using SSHFS
It is theoretically possible to mount an SSH target inside Neurodesktop, but it’s not a very reliable way of mounting storage:
A better option is to use scp and copy data from an SSH endpoint:
scp /neurodesk/myfile user@remoteserver:/data/
An alternative is to mount the SSHFS target into a parent directory on your local machine or VM and then use the -v option in the docker run command to bind the parent directory of the SSHFS mount. NOTE: the SSHFS has to be mounted to a subdirectory inside a parent directory which is then bound to the docker container. If you directly bind to the mounted directory itself, your Neurodesktop container will stop being able to access it if the SSHFS mount disconnects and will not be able to access it again without restarting the Neurodesktop container.
Then add the following line to the docker run command when starting Neurodesktop (note the rshared flag):
-v /SSHFS_Mounts:/data:rshared \
TIP: If you use key pair authentication instead of password for your SSHFS mount, you can use the reconnect flag to reconnect automatically if the connection drops:
Neurodesk provides a containerised data analysis environment to facilitate reproducible analysis of neuroimaging data. Analysis pipelines for neuroimaging data typically rely on specific versions of packages and software, and are dependent on their native operating system. These dependencies mean that a working analysis pipeline may fail or produce different results on a new computer, or even on the same computer after a software update. Neurodesk provides a platform in which anyone, anywhere, using any computer can reproduce your original research findings given the original data and analysis code.
Yes, our project aims to run on the hardware you have access to. However, without docker support you cannot use our desktop interface NeuroDesktop but you can still use the command line interface NeuroCommand on HPC. This works well for batch processing on HPCs once you developed your pipeline in our desktop interface. If your HPC provides a desktop interface you can use all our graphical applications without any issues and the GUIs even work via SSH x-forwarding - it’s not the most performant experience, but it works well enough.
Is there reduced performance when using containers?
If you are running containers on Linux there is no performance penalty - on an HPC with a Lustre filesystem it can even be faster to run our containers than running natively on the filesystem (because meta data operations are shifted to the compute node - more information can be found here: Rioux, Pierre, Gregory Kiar, Alexandre Hutton, Alan C. Evans, and Shawn T. Brown. ‘Deploying Large Fixed File Datasets with SquashFS and Singularity’. ArXiv:2002.06129 [Cs], 14 February 2020. https://arxiv.org/abs/2002.06129 ). However, running Neurodesktop on Windows and Mac will have a performance penalty, because Linux runs in a Hypervisor on these systems.
How can I see how much resources Neurodesk containers need?
In Linux the containers run as normal processes and you can use htop and top to inspect the resource footprint. For Windows and Mac the information is not readily available and we wrote some information here: Troubleshooting
We designed neurodesk with reproducibility as a main goal, so the desktop containers should not be modified if one aims for full reproducibility. However, there is one good option to keep your settings across different container versions: You can write a shell script that installs additional packages and modifies the environment so it’s perfect for you. This script can then be re-executed in a new desktop version and will enable a reproducible customization.
Another option is to “save” your docker container including all changes you made. This could be useful when your changes are too difficult to write a shell script or when you do not care about reproducibility as much and you just want to get the job done. To do this you can commit (https://docs.docker.com/engine/reference/commandline/commit/) your container and by uploading the container to your own docker hub you could even share it.
How to force a complete container download to your system
To increase speed and reliability of Neurodesktop we mount the application containers from a CVMFS mount and download only the files required to run your current task. Although we aim to keep everything on there reproducible, there might be a reason that you want to fully download the containers to your system. You can force this behaviour by adding another parameter to the docker call: -e CVMFS_DISABLE=true
You can copy and paste text within Neurodesktop and between Neurodektop and your host computer using the regular keyboard shortcuts (CTRL+C, CTRL+X, and CTRL+V). Note however that some applications (e.g., command-line terminal) are using other keyboard shortcuts. You can usually find them in the “Edit” menu of the relevant application.
Note for Mac Users: You will need to use a combination of CTRL and Command shortcuts in order to copy and paste text between Neurodesktop and the host computer. For example, copy text from your Mac with Command+C and then paste it into Neurodesktop using CTRL+V. For the other way around, you’d use CTRL+C in Neurodesktop and then Command+V on the Mac.
I cannot copy and paste text within Neurodesktop using keyboard shortcuts
If you’re using Mac, you might be trying to use Mac keyboard shortcuts, but Neurodesktop is using Linux keyboard shortcuts (CTRL+C and CTRL+V)
If you use the terminal, please see “I fixed my internet browser clipboard, but copy or paste still do not work in the terminal” below.
Copying text from my host computer and pasting it inside Neurodesktop doesn’t work in Firefox
This is a “feature” of firefox and you can disable this “feature”:
navigate to about:config and “Accept the Risk and Continue” (“about:config” needs to be entered in the address bar of firefox and hit enter)
now search for clipboard and then set the following to “true”:
dom.events.asyncClipboard.clipboardItem
dom.events.asyncClipboard.read
dom.events.testing.asyncClipboard
Then close firefox and restart. Then the clipboard should work as one would expect.
If the clipboard still does not work, check “I fixed my internet browser clipboard, but …” sections below.
Copy and paste between my host computer and Neurodesktop (or vice versa) doesn’t work in Chrome or Edge
The browsers have a security feature to protect you from something stealing your clipboard content. Depending on your security settings you have to enable it explicitly - it’s a little icon in the browser address bar that looks like a clipboard.
After pressing the icon, you should choose the option shown below in the dialog that opens. After pressing “Done”, close the current browser tab and open a new one for the changes to take effect.
If the clipboard still does not work, check “I fixed my internet browser clipboard, but …” sections below.
I fixed my internet browser clipboard, but copy or paste still do not work in the terminal
The terminal is using special keyboard shortcuts, Shift+CTRL+C for copy, and Shift+CTRL+V for paste. Alternatively, you can copy and paste text by using the terminal’s “Edit” menu.
I fixed my internet browser clipboard, but copy or paste still do not work in the file browser
The copy and paste options in the “Edit” menu of the file browser are used to copy and paste files, not text. To copy and paste text from/into the file browser application (e.g., copy a path into the path field in the top), use the CTRL+C and CTRL+V keyboard shortcuts.
I fixed my internet browser clipboard, but copy or paste still do not work in a specific/all applications
If you’re using Mac, you might be trying to use Mac keyboard shortcuts, but Neurodesktop is using Linux keyboard shortcuts.
For more details, read the “Note for Mac users” here.
It is also possible that the text you are trying to copy includes special characters (e.g., non-English characters), which may cause Neurodesktop to not execute your paste command (including the non specials characters). Give special attention to the following characters:
Dash: the en (short) dash is the normal one and copies ok, but the em (long) dash is considered a special character. When in doubt, replace all the dashes in the text you want to copy with en dashes.
Quotation mark: a strictly vertical quotation mark is fine, but a slightly leaning quotation mark / an apostrophe are special characters. When in doubt, replace all quotation marks in the text you want to copy with vertical quotation marks.
If it still does not work, please report the problem and we will do our best to help you:
Copy some text from your host computer (CTRL+C, or Command+C)
Open the Mousepad text editor in Neurodesktop (Start button → “Accessories” → “Mousepad”)
Try to paste the text using the menu option “Edit” → “Paste”
Try to paste the text again using CTRL+V
If you don’t have one already, please create a Github account here
If you are not logged into Github, please log in (upper right corner)
Press “New Discussion” button
In the message that you write, please specify your operating system, your internet browser, the application in question, and if you can copy/paste to Mousepad and how?
Docker, WSL, Memory
docker: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?.
This is usually a docker-related error, not related to neurodesktop itself. To troubleshoot docker, we can try a simpler container first:
docker run hello-world
Try the following solutions (in this order, until the above command works)
Win/Mac: Open docker GUI and accept T&Cs. Check that the docker engine is running
Linux: Make sure you started the docker daemon (sudo systemctl start docker)
Add your user to the OS docker group (sudo usermod -aG docker $USER)
docker.sock permissions need to be changed (sudo chown root:docker /var/run/docker.sock)
Close and open the terminal and retry.
Log out and login again, or restart the machine (current user environment does not fully know docker is running)
Windows users: WSL not installed properly
The Docker engine relies on the Windows subsystem for Linux (WSL) to run on a windows machine.
Note
We recommend the manual install instructions, as the simplified install requires an upgrade to a preview build of Windows that may be unstable.
If WSL is properly installed, the Resources tab of the Docker settings should look something like this:
However, if WSL is missing or incorrectly configured, the Resources tab of the Docker settings may look something like this:
If this is the case, follow the manual install instructions to install WSL 2 (including installation of Ubuntu through Microsoft Store).
Windows users: Not enough free space on the partition in Windows and WSL2
Windows users: Failure to connect to Neurodesktop in Firefox
We recommend using Microsoft Edge or Google Chrome to access Neurodesktop.
Trouble installing neurodesk images
This may be a memory issue. First, ensure that there is enough free space on the disk. If there is, try resetting docker settings and data. To do this:
Open the docker engine
Navigate to “Troubleshooting” (the bug icon in the top right).
Click “Reset to factory defaults”
If you are still experiencing issues after this, you may need to update docker to the latest version. This can be achieved through “settings” in the docker engine, or (on windows) by right clicking on the docker tray icon:
I got an error message ‘X killed’ or not enough memory
This may be due to Docker not having access to enough RAM from your host computer.
If you are using Docker on MacOS
The memory amount is managed via the Docker settings:
If you are using Docker on Windows 10 with the WSL2 backend
then this is managed by Windows settings. Try the following steps to check how much RAM Docker has access to and increase the amount if necessary.
Run Docker
Open a terminal (ie. Powershell) in the PC you want to use to run Neurodesktop (not in Neurodesktop itself) and type the following command:
docker info
This will generate information about your Docker installation (make sure Docker is running during this step)
In the .wslconfig file include the following lines:
[wsl2]
memory=32GB
Quit Docker (make sure it’s not running in the background, ie. system tray, check task manager)
In the terminal, run the following command
wsl --running --list
This will list any running distributions. For the update to be successful, WSL needs to have completely stopped running (ie. no distributions running)
Restart Docker and rerun steps 1-3 to confirm it was successful
If you are not using WSL2, you can check and manage your RAM allocation in the Docker desktop application.
Open the Docker application and navigate to settings > resources > advances
Scroll down to the Memory option and use the sliding bar to adjust the setting
Click apply and restart
*RAM requirements will vary based on the tools/data you are using. If the system you’re using has limited RAM, test out a few different amounts by running the above steps and then your analyses in Neurodesktop. Version 20220208 onwards has a memory monitor in the taskbar - you can use this to check how much memory Neurodesktop has access to and how much is being used by the analyses being run.
How to empty trash bin in Neurodesktop
If you have deleted files using the Neurodesktop GUI but your storage is not yet emptied, execute the following command in the terminal.
rm -rf ~/.local/share/Trash/
How can I contribute new containers?
We are still working on making this easier, but here is the current workflow to add new applications.
I couldn’t find the information I was looking for. Where can I get additional assistance?
Neurodesk is an open-source project that is always evolving. If you are experiencing an issue not listed here, you can reach out to us on Github.
Post your question at https://github.com/orgs/NeuroDesk/discussions or open a new issue, so that we can aim to solve it and update our help documentation.
How do I get my files in there?
It depends where you are running Neurodesk and where your files are. We provide many different ways from drag-and-drop, to cloud storage to file mounts in Storage in Neurodesk.
