Spatial transcriptomics analyses tend have moderate computational needs and a high degree of interactivity. They can need more ram that is available on a typical laptop or desktop computer, and the continuous need to check and evaluate results makes them ill suited to traditional HPC. A shared managed R server may be available in bioinformatics-focussed groups, but not every bioinformatician has that.

This document outlines how an individual researcher (or group) may get access to a self-managed Rstudio environment, and then set it up for real spatial transcriptomic analyses. It assumes that you have some familiarity with the linux command line and R (or, a willingness to learn).

Specifically - this is via use of the BioShell service; you can check your eligibility here

bios logo

Briefly the steps outlined are:

  1. Apply for a bioshell VM
  2. Login to your VM
  3. Install system libraries
  4. Decide if R version needs to be upgraded, do so if required.
  5. Install R packages
  6. Transfer your data across
  7. Analysis!

Apply for a bioshell VM : with R and Rstudio

For Australian researchers it is recommended to apply for a ‘bioshell’ VM . These machines are built for bioinformatics workloads and come with Rstudio and JupyterLab ready to run.

See the extensive docs and how to apply here: https://sydney-informatics-hub.github.io/BioShell-User-Guide/

Alternatively, if you already have a nectar allocation for your project, you can also build your instance using the bioshell image (e.g. bioshell-v1.0.0)

These instructions assume you’ve got a newly minted bioshell machine, and have successfully logged in (see bioshell docs). They may still be helpful if your VM is from another source.

Login to your VM

See instructions here to connect via SSH

https://sydney-informatics-hub.github.io/BioShell-User-Guide/connecting

Install system libraries

To save time, consider installing some system libraries before trying to install all your R packages.

System libraries can be fast efficient C libraries that R uses in the background to handle number crunching, file format processing, other programming languages or programs.

Installation of system libraries needs root access (sudo), which we should have on our bioshell machine. Once installed, any user may use them.

The posit website provides a command for installation of a collection of oft-used system libraries - a good place to start; https://docs.posit.co/resources/install-r.html#optional-install-system-dependencies-of-common-r-packages

E.g. for the Ubuntu 24.04.4, that’s: (You can see what version your on in the login message)

sudo apt install -y cmake default-jdk gdal-bin git gsfonts libabsl-dev libcairo2-dev libcurl4-openssl-dev libfontconfig1-dev libfreetype6-dev libfribidi-dev libgdal-dev libgeos-dev libgl1-mesa-dev libglpk-dev libglu1-mesa-dev libharfbuzz-dev libicu-dev libjpeg-dev libmagick++-dev libmysqlclient-dev libnode-dev libpng-dev libpoppler-cpp-dev libproj-dev libprotobuf-dev libprotoc-dev libsodium-dev libsqlite3-dev libssh2-1-dev libssl-dev libtiff-dev libudunits2-dev libuv1-dev libwebp-dev libx11-dev libxml2-dev make poppler-data protobuf-compiler python3 tcl texlive tk tk-dev tk-table unixodbc-dev zlib1g-dev

Some further installs that are helpful for spatial analyses;


# for fs package
sudo apt install libuv1-dev

# Image magick tools
#Configuration failed to find the Magick++ library. Try installing:
sudo apt install libmagick++-dev

# Required for packages sf (spatial features, underlies some other packages)
#ERROR: configuration failed for package ‘sf’
sudo apt install libudunits2-dev libgdal-dev libgeos-dev libproj-dev libsqlite3-dev

# fftw (used by alabaster.sfe) via fftwtools
sudo apt install libfftw3-dev libfftw3-doc

# rJava
sudo apt install default-jre

Upgrade R if necessary

Ideally, you won’t need to update R. The bioshell VMs come with a pre-configured R installation ready to go.

However - issues may arise when you need to use ‘bleeding edge’ bioconductor packages. Bioconductor has a 6-monthly release cycle, and strict versioning requirements. Each bioconductor version has a minimum R requirement - and for the very latest this could be less than what is on bioshell!

If you need to work with packages (or versions of those packages) that are only available in a more recent bioconductor release than runs on your R version, then you might consider upgrading your R version. See Bioconductor release announcements

For example; the alabaster.sfe package is used in some spatial sampler examples and requires R >= 4.5.0 (BioC 3.21+), but version one of the bioshell image has R 4.3.3. (NB: Saving data without using alabaster is an alternative.) If you are planning to work primarily within the Seurat ecosystem, this might not be needed.

Upgrading R

The version of R on the bioshell image is the latest packaged version of R that shelley could install. So if you need to use a newer version then that, it’ll have to be installed ‘by hand’.

Coming soon - Upgrading R with shelley

In the future, it should be possible to upgrade R to a newer version via shelley. However, currently, the latest version that shelley has access to is the one installed!

On the command line, list the R versions that Shelley knows about.

  shelley find R

If the version you need is there, install it!

  shelley build r

Restart your rstudio server, and see what version of R it is using. You may still need to update your system R to the freshly installed version.

Since you should have full rights to these VMs, its still possible to update to a later R version in a ‘standard’ way, but its a lot more work and best to have some command line and sysadmin confidence to do this. (Or get assistance from someone who does!)

Step 1: Install R

You’ll first need to determine your OS version, and the R version you want. It is easy to get from the posit servers. See https://docs.posit.co/resources/install-r.html

# check ubuntu version to grab the right command (others might install fine then give library.so errors!)
cat /etc/os-release

export R_VERSION=4.6.1
curl -O https://cdn.posit.co/r/ubuntu-2404/pkgs/r-${R_VERSION}_1_$(dpkg --print-architecture).deb
sudo apt-get update
sudo apt-get install ./r-${R_VERSION}_1_$(dpkg --print-architecture).deb

Now we have a new version of R installed. The old version is still there.

Check it works by opening up an R console on the command line.

/opt/R/${R_VERSION}/bin/R

Step 2: Switch system R to new version

When you have multiple versions of R installed, Rstudio uses the ‘system’ version R of R. Make the newly installed version the ‘system’ version by replacing the R and Rscript symlinks.

# where is my default R?
# Do not have any R modules loaded
which R

# For whatever reason, all the docs seem to assume that the system R is in /usr/local/bin/, but on this server, R is in /usr/bin. 
cd /usr/bin

# Keep the old R links around just in case
sudo mv R Roldsymlink
sudo mv Rscript Rscriptoldsymlink

# Remake them, but this time to R 4.6.1
cd /usr/bin
sudo ln -s /opt/R/${R_VERSION}/bin/R R
sudo ln -s /opt/R/${R_VERSION}/bin/Rscript Rscript

Next continue on to starting up Rstudio and installing packages.

Start up R studio

Now start up R studio, as per the bioshell docs

module load rstudio
#sudo rstudio-server stop # stop it if it was already running. 
sudo rstudio-server start

Installing R packages

Next, you’ll want to install some R packages. Some typical examples for a new setup are listed below, you might not need all of them and almost certainly will want more later!

Consider use of a package manager system like renv, particularly if you’ll be working with multiple projects.

These installations will takes some time to run (by default they’ll compile from source). You might find your session stops responding or disconnects - just reconnect and run again if needed, the commands will pick up from where they left. See next section for dealing with some common errors.

If you need to upgrade from an older bioconductor release

If you’ve already been working with a previous verison of BiocManager (e.g. you already tried a previous R version on this machine and found you needed to upgrade), you’ll need to update your biocondutor version to the desired version. On a fresh install this isn’t neccessary, BiocManager will simply find the latest.

install.packages("BiocManager")
BiocManager::install(version = "3.23")

Install some R packages from CRAN;

install.packages ( c(
  "BiocManager",
  'remotes',
  'tidyverse',
  'DT',
  'patchwork',
  'ggrepel',
  'Seurat'
  ) )

Install some R packages from bioconductor

BiocManager::install(c(
  'SpatialExperiment',
  'scuttle',
  'scater',
  'limma',
  'edgeR',
  'BiocParallel',
  'alabaster.sfe', # skip if not planning to use bioconductor packages on upgraded R, requires 'bleeding edge' packages.
  'Voyager'        # skip if not planning to use bioconductor packages on upgraded R, requires 'bleeding edge' packages.
))

Install a few things from github.

remotes::install_github("immunogenomics/presto") # Dramatic speed up of certain operations in Seurat.

Its not working! Handling R package install errors

If you get an error in install, it is often due to a dependency of a package you need, not the package itself. It can be helpful to look for a message like ‘dependency ’x’ was not installed’. Try to install package ‘x’ on its own - you’ll get to the error much quicker and can fix it.

Some common problems:

  • Package not available : ’ package ‘XYZ’ is not available for this version of R
    • Typo in package name
    • This is a bioconductor package, and you’re trying to install it with ‘install.packages()’. Use BiocManager()
    • This is a bioconductor package, but it is too new to be on the bioconductor release you are using (which in term is limited to your R version - see here. On your package’s bioconductor page you can see ‘in bioconductor since’ for the release version needed, (and the ‘all versions’ link for finding out what version was available for previous bioconductor releases.
    • This package isn’t in CRAN or bioconductor - Typically you’ll install these directly from a github repo with devtools (see above)
  • Missing system library : Typically this error will offer up ‘apt install’ command or name of a system library that is needed. Sometimes it doesn’t, and you’ll need to search online for what you do need to install.
  • System library configuration issue: Some packages need further configuration before they work, consult installation instructions for those libraries (e.g. rJava)

For further information on R installation errors;

Transferring your data

To get large spatial datasets across to your VM, globus is the recommended method - detailed instructions are here

An alternative for small files would be SFTP via a tool like filezilla(client) - you’ll need to configure with your IP address, username and password.

Handling RAM errors (OOM Crashes)

Some analysis steps are RAM heavy, and sometimes you’ll find that certain steps will reliably crash your R session. If you believe your data is too large for your VM - you can request more (at the cost of running through your service unit allocation faster!). Its generally best to start small and scale up - see advice on flavours

For example, on nectar: https://support.ehelp.edu.au/support/solutions/articles/6000212271-resizing-nectar-instances

Note that some methods just shouldn’t be run on these kind of datasets without using some ‘smart’ data handling e.g. Counts matrix should be stored as sparse matrices (never dense matrices). You might split some analyses by sample e.t.c

Analysis!

Happy analysis - May your data be clean and your sample sizes be adequate!


sessionInfo()
R version 4.6.1 (2026-06-24)
Platform: x86_64-pc-linux-gnu
Running under: Ubuntu 26.04.1 LTS

Matrix products: default
BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3 
LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.32.so;  LAPACK version 3.12.0

locale:
 [1] LC_CTYPE=en_AU.UTF-8       LC_NUMERIC=C              
 [3] LC_TIME=en_AU.UTF-8        LC_COLLATE=en_AU.UTF-8    
 [5] LC_MONETARY=en_AU.UTF-8    LC_MESSAGES=en_AU.UTF-8   
 [7] LC_PAPER=en_AU.UTF-8       LC_NAME=C                 
 [9] LC_ADDRESS=C               LC_TELEPHONE=C            
[11] LC_MEASUREMENT=en_AU.UTF-8 LC_IDENTIFICATION=C       

time zone: Etc/UTC
tzcode source: system (glibc)

attached base packages:
[1] stats     graphics  grDevices datasets  utils     methods   base     

other attached packages:
[1] workflowr_1.7.2

loaded via a namespace (and not attached):
 [1] jsonlite_2.0.0      compiler_4.6.1      BiocManager_1.30.27
 [4] renv_1.2.4          promises_1.5.0      Rcpp_1.1.2         
 [7] stringr_1.6.0       git2r_0.36.2        callr_3.8.0        
[10] later_1.4.8         jquerylib_0.1.4     yaml_2.3.12        
[13] fastmap_1.2.0       R6_2.6.1            knitr_1.52         
[16] tibble_3.3.1        rprojroot_2.1.1     bslib_0.12.0       
[19] pillar_1.11.1       rlang_1.3.0         cachem_1.1.0       
[22] stringi_1.8.9       httpuv_1.6.17       xfun_0.61          
[25] getPass_0.2-4       fs_2.1.0            sass_0.4.10        
[28] otel_0.2.0          cli_3.6.6           magrittr_2.0.5     
[31] ps_1.9.3            digest_0.6.39       processx_3.9.0     
[34] rstudioapi_0.19.0   lifecycle_1.0.5     vctrs_0.7.3        
[37] evaluate_1.0.5      glue_1.8.1          whisker_0.4.1      
[40] rmarkdown_2.32      httr_1.4.9          tools_4.6.1        
[43] pkgconfig_2.0.3     htmltools_0.5.9