What's on this page:

1. New on Linux systems?
2. Common Commands
3. Text editing in command line
4. Displaying images in command line
5. Displaying images from command line (using X11 forwarding)
6. Displaying NIFTI images in command line
7. X11 Forwarding

This page contains some tips on how to get started using the psychp01 cluster if you are not too familiar with Linux/Unix. The information is intended for both users that are new to psychp01 and for users that are new to Linux/UNIX-like operating systems. Please consult the rest of the user guide for information that is not covered in this chapter.

Please also visit this MIT course on basics shell commands and command line environment.

On a terminal, you can use ssh to login to psychp01. Check the Access to psychp01 through Command Line in this documentation to learn more about ssh.

To transfer any file or data you wish to use to the cluster, you can use file transfer clients, such as scp or sftp. For more info, see Transferring files to/from psychp01.

You must execute your jobs by submitting them to the batch system using bash files. There is a dedicated section on bash files and batch system in our user guide that explains how to use the batch system. The pages explain how to write job scripts, and how to submit, manage, and monitor jobs. It is not allowed to run long or large memory jobs interactively (i.e., directly from the command line).

Provide the full path name of the directory you are currently in:

pwd

Change the current working directory:

cd

List the files and directories which are located in the directory you are currently in:

ls

Searches through one or more directory trees of a file system, locates files based on some user-specified criteria and applies a user-specified action on each matched file:

find

Find specific files, you can use the -name and -type arguments:

find . -name 'my*' -type f

The above command searches in the current directory (.) and below it, for files and directories with names starting with my. “-type f” limits the results of the above search to only regular files, therefore excluding directories, special files, pipes, symbolic links, etc. my* is enclosed in single quotes (apostrophes) as otherwise the shell would replace it with the list of files in the current directory starting with “my”.

Find a certain expression in one or more files:

grep

For example, to find the string apple in the fruitlist.txt text file, type:

grep apple fruitlist.txt

Create new directory:

mkdir

Remove a file. Use with caution:

rm

Remove a directory. Use with caution:

rmdir

Move or rename a file or directory:

mv

Edit text files in command line (for more details, see below Text editing in command line):

vi

or

vim

View (but do not change) the contents of a text file one screen at a time, or, when combined with other commands (see below Text editing in command line) view the result of the command one screen at a time. Useful if a command prints several screens of information on your screen so quickly, that you don’t manage to read the first lines before they are gone.

less

and

more

Use the “pipe” or “vertical bar” to group two or more commands together:

|

For example, list files in the current directory (ls), retain only the lines of ls output containing the string “key” (grep), and view the result in a scrolling page (less), type:

ls -l | grep key | less    

A complete listing of the defined variables and their meanings can be obtained by typing:

printenv

You can define (and redefine) your own variables by typing:

export VARIABLE=VALUE

If you know the UNIX-command that you would like to use but not the exact syntax, consult the manual pages on the system to get a brief overview. Use man + command for this. For example, to get the right options to display the contents of a directory, use:

man ls

To choose the desired options for showing the current status of processes, use

man ps

A popular tool for editing files (e.g., your code) on Linux/UNIX-based systems is vi. Unfortunately, the commands within both vi editor are quite cryptic for beginners. It is probably wise to spend some time understanding the basic editing commands before starting to program the machine.

For quick help, use:

man vi

or

man vim

Suppose you want to check the progress of your analyses. Suppose that you defined in your bash file that SLURM is supposed to output the status of your analyses in a text file (see here) named job_out.txt stored in your analyses folder in your home directory /home/gbellucci. To quickly check the status of your analyses, you would first establish an ssh connection with the cluster, then cd to your analyses folder and type vim job_out.txt, like that:

ssh gbellucci@psychp01.rhul.ac.uk
gbellucci@psychp01.rhul.ac.uk's password:
gbellucci@psychp01:~$ cd /home/gbellucci/analyses
gbellucci@psychp01:~$ vim job_out.txt

This would open the file in your command window. You can scroll and check the status of your analyses. To exit just type:

:q

Every file opened with vim will be in a non-writable state. To write in your opened file, press

i

On the bottom left of your command line, you will see the word INSERT appear, like that:

1. -INSERT–

Modify your file as you wish. When done, press ESC on your keyboard. This will make the word INSERT disappear. You are again back to a non-writable state. To save and exit, type:

:wq

Where w stands for “write” and q for “quit”. If you change your mind and decide to exit without saving your changes, just type

:q!

This will not write your changes and force an exit (that's why the !) from vim.

The easiest way to display images is to use niicat (see here). For that, you would not need an X11 forwarding connection (see X11 forwarding below), as it prints the image in your terminal using libsixel. niicat can display niftii, png, jpg, or similar images. Importantly, though, to display images with niicat, you need to work on a terminal that supports sixel (see here).

For macOS, you could use iTerm2. Once installed, open iTerm2 and establish an ssh connection to the remote desktop (see Cluster access). For example:

ssh gbellucci@psychp01.rhul.ac.uk

Now, suppose that you have a NIFTI image named anatomical_brain.nii in the folder fmri_results in your home /home/gbellucci. You can open the image like that:

niicat -lb /home/gbellucci/fmri_results/anatomical_brain.nii

The -lb option tells niicat to use libsixel-bin to display the image in your terminal.

Another option to open an image saved on a remote server is to establish an X11 forwarding connection to the server and use an image viewer. For that, you need to:

1. Ensure you have X11 installed on your local machine (XQuartz on macOS, typically installed X server on Linux).
2. Enable X11 forwarding when connecting via SSH.

For example, first make sure XQuartz is currently running on your machine. Before connecting to the remote server, you can start XQuartz on your local machine by typing the following in a terminal window:

open -a XQuartz

You then would need to establish a X11 forwarding connection like that (see Cluster access for more information):

ssh -X username@remote_server

For example, suppose your username is gbellucci and the remote server is psychp01.rhul.ac.uk, you would need to type:

ssh -X gbellucci@psychp01.rhul.ac.uk

You will be prompted to enter a password. Afterwards, suppose that you have a beautiful image named my_beautiful_result_image.jpg in the folder results in your home /home/gbellucci. You can open your image by using fim like that:

fim /home/gbellucci/results/my_beautiful_result_image.jpg

You can also open your image by using Eye of GNOME, which tends to display images with higher resolution:

eog /home/gbellucci/results/my_beautiful_result_image.jpg

To quickly preview neuroimaging images in NIFTI format on the terminal, you can use niicat (see here). For that, you would not need an X11 forwarding connection, as it prints the image in your terminal using libsixel. niicat can display niftii, png, jpg, or similar images. Importantly, though, to display images with niicat, you need to work on a terminal that supports sixel (see here).

For macOS, you could use iTerm2. Once installed, open iTerm2 and establish an ssh connection to the remote desktop (see Cluster access). For example:

ssh gbellucci@psychp01.rhul.ac.uk

Now, suppose that you have a NIFTI image named anatomical_brain.nii in the folder fmri_results in your home /home/gbellucci. You can open the image like that:

niicat -lb /home/gbellucci/fmri_results/anatomical_brain.nii

The -lb option tells niicat to use libsixel-bin to display the image in your terminal.

X11 forwarding is a feature that allows you to run graphical applications installed on a remote server and display them on your local machine as if they were running locally. The “X11” part refers to the X Window System (version 11), which is a protocol and system for managing graphical displays on UNIX and UNIX-like operating systems.

This is how it works:

1. Local X Server: Your local machine runs an X server. This is a software component responsible for managing the display and input devices (like keyboard and mouse) for graphical applications.
2. Remote Application: The remote machine runs the graphical application. Instead of displaying the graphical output on the remote machine’s screen, it sends this output to your local X server.
3. SSH Tunnel: The graphical output is sent securely over the network using SSH (Secure Shell, see Cluster access). SSH creates a tunnel between your local machine and the remote server, carrying the X11 protocol data.

X11 forwarding is primarily designed for UNIX-like operating systems, such as Linux and BSD. However, it can also be used on macOS and Windows with some additional setup.

Linux distributions typically have X11 forwarding support built-in. macOS uses XQuartz, an implementation of the X server for macOS. You need to install and run XQuartz to use X11 forwarding. You can easily install XQuartz via the Terminal using Homebrew. In a Terminal window, just type:

brew install --cask xquartz

The setup of X11 Forwarding is pretty easy in macOS/Linux.

1. Ensure your local machine has an X server running (like XQuartz on macOS).
2. Connect to the remote server with the -X or -Y option:

First make sure an X server is currently running on your machine. For instance, if you are working on macOS and use XQuartz, before connecting to the remote server, you can start XQuartz on your local machine by typing the following in a terminal window:

open -a XQuartz

You then would need to establish a X11 forwarding connection like that (see Cluster access for more information):

ssh -X username@remote_server

For example, suppose your username is gbellucci and the remote server is psychp01.rhul.ac.uk, you would need to type:

ssh -X gbellucci@psychp01.rhul.ac.uk

For trusted X11 forwarding, you can use the -Y option like that:

ssh -Y gbellucci@psychp01.rhul.ac.uk

Both -X and -Y options allow you to run graphical applications from a remote server and display them on your local machine, but there are important differences in terms of security and functionality. The -X option or untrusted X11 Forwarding is the more secure option because it restricts the level of access that the remote application has to your local X server. Specifically, it limits the remote application’s ability to interact with other X11 clients and monitor or modify your local desktop environment. Even if more secure, with the -X option you might experience restrictions on some functionalities of the remote graphical applications. You can employ the -X option for general use, especially when you are unsure about the security of the remote applications you are running. It helps to prevent potential security risks from untrusted remote applications.

On the contrary, the -Y option enables trusted X11 forwarding, allowing the remote application to have full access to your local X server. It can interact with other X11 clients and modify your local desktop environment, just like a local application. This implies that the -Y option will give you full functionality for remote graphical applications, but it also removes the restrictions imposed by the -X option, which means that applications that need more direct access to the X server will work correctly. You can use the -Y option if you need full functionality from the remote graphical applications and you trust the remote server and the applications you are running. Since it allows more access, it should only be used in secure, trusted environments.

Windows does not natively support X11 forwarding because it does not use the X Window System. However, you can use third-party software like Xming, VcXsrv, or MobaXterm to run an X server on Windows. Combine these with an SSH client like PuTTY or use the built-in SSH in Windows 10 (using the Windows Subsystem for Linux, WSL). See here for more information.

Getting Started with HPC on psychp01Cluster access
Return to Table of ContentsReturn to main page