Sign inSign up

rnakato/shortcake

By rnakato

•Updated 8 days ago

A docker image for single-cell analysis, based on ubuntu 24.04

Image
Data science
8

8.9K

rnakato/shortcake repository overview

⁠ShortCake🍰

ShortCake is an integrated platform for efficient and reproducible single-cell analysis using the Docker system⁠.

⁠0. Changelog

See Changelog⁠

⁠1. Included tools (v4.0.0)

(The tools that cannot be installed due to unresolved errors are crossed out.)

For SATURN⁠, the saturn environment provides its dependencies (torch 1.10.2+cu113, torchvision, pytorch-lightning, scanpy) but not SATURN itself: the repository is cloned during the build only to resolve requirements.txt and is then removed. Clone it yourself and run it inside that environment.

  • Database (genome): BSgenome.Hsapiens.UCSC.hg19, BSgenome.Hsapiens.UCSC.hg38, BSgenome.Mmusculus.UCSC.mm10, BSgenome.Scerevisiae.UCSC.sacCer3, BSgenome.Dmelanogaster.UCSC.dm6
  • Database (gene): EnsDb.Hsapiens.v75, EnsDb.Hsapiens.v79, EnsDb.Hsapiens.v86, EnsDb.Mmusculus.v79
  • Database (motif): JASPAR2016, JASPAR2018, JASPAR2020, JASPAR2022, JASPAR2024
  • SeuratData: ifnb_3.1.0, panc8_3.0.2, pbmcsca_3.0.0, pbmc3k_3.1.4, celegans.embryo_0.1.0, cbmc_3.1.4, hcabm40k_3.0.0, thp1.eccite_3.1.5, stxBrain_0.1.1, stxKidney_0.1.0, bmcite_0.3.0, pbmcMultiome_0.1.2, ssHippo_3.1.4

⁠2. Flavors of ShortCake

The ShortCake Docker image is large, at about 100 GB.

Since ShortCake version 3, we have created several flavors to reduce the size of the image and make it easier to use, as shown below.

  • shortcake_seurat: Contains only Seurat and its related packages.
  • shortcake_r: Contains additional R packages installed on top of shortcake_seurat. Jupyter notebook is available, but Python tools are not installed.
  • shortcake_light: Installs the shortcake_default environment on top of shortcake_r. This flavor includes Seurat, Scanpy, Monocle3, and scVelo, and is sufficient for most users.
  • shortcake: Installs almost all Python virtual environments on top of shortcake_light. The only exceptions are the scVI and rapids_singlecell environments.
  • shortcake_scvi: Installs the scVI environment on top of shortcake_light.
  • shortcake_rapidsc: Installs the shortcake_rapidsc environment on top of shortcake_light.
  • shortcake_full: The full image with all tools installed.

For example, you can use shortcake_light version 4.0.0 with this command:

docker run --rm -p 8888:8888 -it rnakato/shortcake_light:4.0.0 jupyternotebook.sh

⁠3. Run

⁠3.1 Docker

For Docker:

You can pull (download) the ShortCake docker image with this command:

docker pull rnakato/shortcake:<version>

Then you can run ShortCake with the command:

# Container login
docker run [--gpus all] --rm -it rnakato/shortcake /bin/bash

# Execute jupyter notebook (see 'mnt/' directory in the notebook )
docker run [--gpus all] --rm -p 8888:8888 -v (your directory):/work/mnt rnakato/shortcake jupyternotebook.sh
  • The --gpus all option is necessary when using a GPU (e.g., scvi-tools).
  • The -p 8888:8888 option maps the container's port 8888 to the host's port 8888. This allows you to access the Jupyter notebook from your web browser.
  • The -v (your directory):/work/mnt option mounts your local directory to the /work/mnt directory in the container. You can change (your directory) to the path of your local directory where you want to save or load data. In the Jupyter notebook, you can see the /work/mnt directory.

For more information about Docker, see the original website⁠.

⁠3.2. Apptainer

(Note: Singularity has recently been renamed Apptainer⁠.)

You can build the apptainer file (.sif) of ShortCake with this command:

apptainer build -F shortcake.sif docker://rnakato/shortcake

Instead, you can download the apptainer image of ShortCake from our Dropbox⁠ (We use apptainer version 1.4.2).

Then you can run ShortCake with the command:

# Execute Jupyter Notebook (Python and R)
apptainer exec [--nv] shortcake.sif jupyternotebook.sh

# Execute RStudio Server
apptainer exec [--nv] shortcake.sif rserver.sh <port>

# Execute R directory
apptainer exec [--nv] shortcake.sif R

The --nv option is needed if you use a GPU.

⁠4. Usage

⁠4.1 Virtual environments for Python

To avoid version conflicts between tools, we created several Python environments with micromamba⁠. You can see the list of environments installed in the image with micromamba env list command as follows:

$ docker run -it --rm rnakato/shortcake:4.0.0 micromamba env list
    Name                           Active  Path
    ─────────────────────────────────────────────────────────────────────────────────────────────
      base                           *       /opt/micromamba
      cell2cell-screadsim                    /opt/micromamba/envs/cell2cell-screadsim
      celloracle                             /opt/micromamba/envs/celloracle
      cellphonedb                            /opt/micromamba/envs/cellphonedb
      cellrank                               /opt/micromamba/envs/cellrank
      decoupler-liana-sctriangulate          /opt/micromamba/envs/decoupler-liana-sctriangulate
      dynamo                                 /opt/micromamba/envs/dynamo
      episcanpy                              /opt/micromamba/envs/episcanpy
      genes2genes-mowgli                     /opt/micromamba/envs/genes2genes-mowgli
      ikarus-novosparc                       /opt/micromamba/envs/ikarus-novosparc
      mario                                  /opt/micromamba/envs/mario
      metacells                              /opt/micromamba/envs/metacells
      moscot                                 /opt/micromamba/envs/moscot
      scanpy                                 /opt/micromamba/envs/scanpy
      scenic                                 /opt/micromamba/envs/scenic
      scenicplus                             /opt/micromamba/envs/scenicplus
      seacells                               /opt/micromamba/envs/seacells
      shortcake_default                      /opt/micromamba/envs/shortcake_default
      squidpy                                /opt/micromamba/envs/squidpy

Note that the base environment does not include any tools other than Jupyter notebook and EEISP. shortcake_default is the default environment with Python3.10 and contains vairous tools as below:

  • harmonypy
  • autogenes
  • bbknn
  • cellmap
  • celltypist
  • doubletdetection
  • magic-impute
  • constclust
  • multivelo
  • screcode
  • scrublet
  • snapatac2
  • velocyto
  • scranPY
  • phate
  • scib
  • scanorama

The other environments are named after the tools they contain.

⁠4.2 Jupyter

We recommend using Jupyter Notebook (JupyterLab) to use ShortCake:

apptainer exec shortcake.sif jupyternotebook.sh

Specify the appropriate kernel (environment) to use them. In addition, the R command and all R tools are usable in the R kernel.

jupyter_kernel
⁠4.3 Rstudio

ShortCake also provides the Rstudio environment. We recommend using Rstudio server as follows:

# Docker
docker run -it -p 8787:8787 --rm rnakato/shortcake_light:4.0.0 rserver.sh 8787
# Apptainer
apptainer exec shortcake.sif rserver.sh 8787

8787 is the port number, which you can change if necessary. Then, access http://localhost:8787 from your web browser. The default username and password are both rstudio.

You can also run Rstudio directly without a server:

apptainer exec shortcake.sif rstudio

Note that Rstudio requires a GUI (Graphical User Interface) environment, so you will need to set up X11 forwarding to use it.

⁠4.4 Command line

Several single-cell tools provide command-line tools. For example, velocyto⁠ provides the command velocyto run10x to generate a .loom file. It can be executed as follows:

apptainer exec shortcake.sif velocyto run10x -m repeat_msk.gtf <10Xdir> <gtf>

To use a virtual environment from the command line, activate it with the run_env.sh script:

apptainer exec shortcake.sif run_env.sh <environment> <command>

# Example to activate "celloracle" environment
apptainer exec shortcake.sif run_env.sh celloracle python -c "import celloracle"

It is also possible to log directly into the ShortCake container and work inside it using the command-line interface.

docker run --rm -p 8888:8888 rnakato/shortcake /bin/bash

⁠5. Build the image from Dockerfile

First, clone and move to the repository

git clone https://github.com/rnakato/ShortCake
cd ShortCake

⁠5.1 Get your GitHub token

Since the Dockerfile installs many packages from GitHub, first get a GitHub token from your own repository⁠. Next, create Docker_R/.env and Docker_Python/.env files and store the token as follows:

GITHUB_PAT=<your_GitHub_token>

⁠5.2 Build shortcake_seurat and shortcake_r

Move Docker_R directory:

cd Docker_R/

Download the SeuratData⁠ dataset using wget.sh in the Docker_R/SeuratData directory:

cd SeuratData/
sh wget.sh

Then build packages:

cd Docker_R
# build shortcake_seurat only
docker compose -f compose.yaml build seurat
# build shortcake_r only
docker compose -f compose.yaml build r

⁠5.3 Build other flavors

Move to 'Python' directory:

cd ../Docker_Python/

Then build Python packages:

# build shortcake_light
docker compose -f compose.yaml build light
# build shortcake
docker compose -f compose.yaml build default
# build shortcake_full
docker compose -f compose.yaml build full
# build shortcake_scvi
docker compose -f compose.yaml build scvi
# build shortcake_rapidsc
docker compose -f compose.yaml build rapidsc

⁠6. Citation

Please cite this reference when using Shortcake in your study.

  • Nakato R, Nagai LAE. ShortCake: An integrated platform for efficient and reproducible single-cell analysis, Bioinformatics, 2025. DOI: 10.1093/bioinformatics/btaf559⁠

Tag summary

Content type

Image

Digest

sha256:8f6e3f04b…

Size

30.8 GB

Last updated

8 days ago

docker pull rnakato/shortcake