Run labs in container

Note

Three different toolkits, namely Seurat (R/RStudio), Bioconductor (R/RStudio) and Scanpy (Python/Jupyter) are available to perform the scRNAseq analysis. The labs can be run on Uppmax using Singularity (Apptainer) or on your local machine using Docker. Both options provide the necessary environment to run the analysis.
If you use Uppmax, you do not need any local installation or setup on your system but you need an Uppmax account and become a member of the Uppmax projects. If you use Docker, you will need to set up and run Docker yourself.

1 Option A: Run Singularity on Uppmax (Recommended)

1.1 Configure Uppmax

1.1.1 Storage

This setup needs to be run only once at the beginning of the workshop. It will connect you to Uppmax and create a folder with your username in the workshop’s directory.

First connect to Uppmax. Replace <username> with your actual user name.

ssh -Y <username>@rackham.uppmax.uu.se

Once you are connected, change into the working directory that you created in the Precourse instructions.

# change to project directory
cd /proj/naiss2023-23-648/nobackup/<username>

Now we can fetch the scripts for the labs.

git clone --depth 1 --single-branch --branch master https://github.com/nbisweden/workshop-scRNAseq.git
cd workshop-scRNAseq/compiled/labs

Navigate to compiled/labs/<topic> directory to work on labs. And <topic> is either seurat, bioc or scanpy.

1.1.2 Compute

To run the labs you need to first create an interactive session.

Connect to Uppmax and change into your working directory (if not already done):

ssh -Y <username>@rackham.uppmax.uu.se
cd /proj/naiss2023-23-648/nobackup/<username>/workshop-scRNAseq/compiled/labs

Then start an interactive session:

interactive -A naiss2023-22-1345 -p core -n 4 -t 08:00:00

Important

Run the interactive command above only ONCE per day at the beginning of the practical session.

This command will connect you to a node with 5 cores for a duration of 8 hours. You can check the node name under the NODELIST column in the output of the following command:

squeue -u <username>

If you are disconnected from the interactive session, you can re-connect to your node with the following command:

ssh -Y <nodename>

If you get disconnected from Uppmax, reconnect to Uppmax as shown in the very first step, then check your job is running using squeue and login to the compute node as shown in the above step.

1.2 Launch RStudio

Tip

To avoid running out of memory, restart R (Session > Restart R) after each lab.

1.2.1 Seurat

To launch RStudio server and run the Seurat labs perform the following steps:

cd /proj/naiss2023-23-648/nobackup/<username>/workshop-scRNAseq/compiled/labs/seurat
/sw/courses/scrnaseq/singularity/launch_rstudio.sh /sw/courses/scrnaseq/singularity/2024-seurat-r4.3.0.sif

1.2.2 Bioconductor

To launch RStudio server and run the Bioconductor labs perform the following steps:

cd /proj/naiss2023-23-648/nobackup/<username>/workshop-scRNAseq/compiled/labs/bioc
/sw/courses/scrnaseq/singularity/launch_rstudio.sh /sw/courses/scrnaseq/singularity/2024-bioconductor-r4.3.0.sif

1.3 Connect to RStudio

After executing the launch_rstudio.sh script, a message with your login credentials will be printed to your screen, and it looks similar to the one below.

Important

Do not close this terminal!

        *************************************************
        *                                               *
        *  IMPORTANT: Do not close or exit this shell!  *
        *                                               *
        *************************************************

1. SSH tunnel from your workstation using the following command:

   ssh -N -L 8787:r483.uppmax.uu.se:58359 susanner@rackham3.uppmax.uu.se

   and point your web browser to http://localhost:8787

2. log in to RStudio Server using the following credentials:

   user: susanner
   password: scrnaseq

When done using RStudio Server, terminate the job by:

1. Exit the RStudio Session ("power" button in the top right corner of the RStudio window).
2. Issue the following command in both shells:

      CTRL-C

Follow the instructions printed on the screen to launch the RStudio Server. Open a shell locally and run your ssh command from step 1. Then open localhost:8787 in your web browser and log in to the RStudio Server using your username and password provided in step 2.

In RStudio, make sure you are in the correct working directory else set it.

getwd()
setwd('/crex/proj/naiss2023-23-648/nobackup/<username>/workshop-scRNAseq/compiled/labs/<topic>')

1.4 Launch JupyterLab

1.4.1 Scanpy

To launch JupyterLab and run the Scanpy labs using Jupyter notebooks perform the following steps:

Tip

To avoid running out of memory, restart the kernel (Kernel > Restart Kernel) after each lab.

cd /proj/naiss2023-23-648/nobackup/<username>/workshop-scRNAseq/compiled/labs/scanpy
/sw/courses/scrnaseq/singularity/launch_jupyter.sh /sw/courses/scrnaseq/singularity/2024-scanpy-py3.10.sif

1.5 Connect to JupyterLab

After executing the launch_jupyter.sh script, a message with your login credentials will be printed to your screen, and it looks similar to the one below.

Important

Do not close this terminal!

        *************************************************
        *                                               *
        *  IMPORTANT: Do not close or exit this shell!  *
        *                                               *
        *************************************************

1. SSH tunnel from your workstation using the following command:

   ssh -N -L 8888:r483.uppmax.uu.se:34968 susanner@rackham1.uppmax.uu.se

   point your web browser to http://localhost:8888/lab

2. Log in to JupyterLab using the password:

   scrnaseq

When done using JupyterLab, terminate the job by:

1. Shut down all kernels.
2. Issue the following command in both shells:

   CTRL-C

Follow the instructions to launch the JupyterLab. Open a shell locally and run your ssh command from step 1. Then open localhost:8888/lab in your web browser and log in to the JupyterLab using the password provided in step 2.

2 Option B: Run Docker Locally

Important

The docker containers are not tested on Microsoft Windows OS.

2.1 Local Setup

Create a new directory at a suitable location. Now you can fetch the scripts for the labs. You can either download individual .qmd or .ipynb files from the Contents page or clone the whole repo. If you clone the repo, navigate to compiled/labs to work on labs.

git clone --depth 1 --single-branch --branch master https://github.com/nbisweden/workshop-scRNAseq.git
cd workshop-scRNAseq/compiled/labs

If the git command is not available, you can simply go to https://github.com/NBISweden/workshop-scRNAseq and download the repo as a zip file and unzip it in a suitable location.

2.2 Images

Separate Docker images are made available for Seurat, Bioconductor and Scanpy toolkits. An additional set of images are available for spatial analyses. All images follow the registry/username/image:tag convention. The image is always ghcr.io/nbisweden/workshop-scrnaseq. Add the appropriate tag based on the lab you are running.

An overview of the available docker images. Note the space requirements.

Topic	Image	Size (GB)
Seurat	`2024-seurat-r4.3.0`	8.87
Bioconductor	`2024-bioconductor-r4.3.0`	7.89
Scanpy	`2024-scanpy-py3.10`	3.68

Optional Topic	Image	Size (GB)
Seurat spatial	`2024-seurat_spatial-r4.3.0`	6.85
Bioconductor spatial	`2024-bioconductor_spatial-r4.3.0`	6.47
Scanpy spatial	`2024-scanpy_spatial-py3.10`	3.68

2.3 Seurat

Tip

To avoid running out of memory, restart R (Session > Restart R) after each lab.

cd /path/to/labs  # replace this with the full path to the workshop compiled lab folder
docker pull --platform=linux/amd64 ghcr.io/nbisweden/workshop-scrnaseq:2024-seurat-r4.3.0
docker run --platform=linux/amd64 --rm -p 8788:8787 -e PASSWORD=scrnaseq -v ${PWD}:/home/rstudio/workdir ghcr.io/nbisweden/workshop-scrnaseq:2024-seurat-r4.3.0

Do not close the terminal. In the browser, go to localhost:8788.
Use the following credentials to log in to the RStudio Server:

User: rstudio
Password: scrnaseq

Navigate to /home/rstudio/workdir/ and open qmd files

2.4 Bioconductor

Tip

To avoid running out of memory, restart R (Session > Restart R) after each lab.

cd /path/to/labs  # replace this with the full path to the workshop compiled lab folder
docker pull --platform=linux/amd64 ghcr.io/nbisweden/workshop-scrnaseq:2024-bioconductor-r4.3.0
docker run --platform=linux/amd64 --rm -p 8789:8787 -e PASSWORD=scrnaseq -v ${PWD}:/home/rstudio/workdir ghcr.io/nbisweden/workshop-scrnaseq:2024-bioconductor-r4.3.0

Do not close the terminal. In the browser, go to localhost:8789. Use the following credentials to log in to the RStudio Server:

User: rstudio
Password: scrnaseq

Navigate to /home/rstudio/workdir/ and open qmd files

2.5 Scanpy

Tip

To avoid running out of memory, restart the kernel (Kernel > Restart Kernel) after each lab.

cd /path/to/labs  # replace this with the full path to the workshop compiled lab folder
docker pull --platform=linux/amd64 ghcr.io/nbisweden/workshop-scrnaseq:2024-scanpy-py3.10
docker run --platform=linux/amd64 --rm -p 8888:8888 -v ${PWD}:/home/jovyan/workdir ghcr.io/nbisweden/workshop-scrnaseq:2024-scanpy-py3.10

Do not close the terminal. At the end of the prompt, you will see a URL that starts with http://127.0.0.1, similar to the one below:

http://127.0.0.1:8888/lab?token=0a1d9ec51b91528a1d1fe2ad2c74f59ecb94c47070c2911d

Note that your token value will be different. Copy the entire URL (with the token) and paste it in your browser.