Single-Cell RNA-seq Time Course of Axolotl Limb Regeneration

This repository contains scripts to preprocess Seurat objects, generate ShinyCell2 files, and deploy an interactive Shiny app for visualization of axolotl limb regeneration scRNA-seq data.

The original data are from: https://doi.org/10.1038/s41467-018-07604-0

01_PreProcessing

Prepares Seurat objects with aesthetic changes.

The Seurat objects were edited using the script "Seurat_EditsV2.R".

This script does the following:
1. Changes the "group" object name to "timepoint"
2. Renames the umap.cca and umap_immune reduction keys to "UMAP" for the merged and immune.filtered objects
3. Wraps the metadata colnames "annotated_celltype" at width = 18 for better x-axis visualization in app
3. Saves the edited objects as new .rds files in the same directory 

To run: ensure the original Seurat objects are in the "01_PreProcessing/" directory.

The following original .rds objects were used:
1. "20251212.merged_copy.rds"
2. "20251212.immune_filtered_copy.rds"

The following edited .rds objects were used in the app making pipeline:
1. "20260421.merged.edit.rds"
2. "20260421.immune_filtered.edit.rds"

02_MakeShinyFiles

Generates ShinyCell2 configuration and app files.

The Shiny files were created using the script "makeShinyAppV4.R".

This script does the following:
1. Creates the shiny cell configs for both merged and immune objects.
2. Edits the metadata (removes "orig.ident", "unintegrated_clusters", "seurat_clusters",
 "cca_clusters", "RNA_snn_res.0.5" from the merged and "orig.ident", "unintegrated_clusters", "seurat_clusters",
 "cca_clusters", "RNA_snn_res.0.5", "RNA_snn_res.0.75", "cytetype_annos", "cond_rep" from the immune object).
3. Sets up the "03_App/" to store the generated files.
4. Makes the shiny files with the specified UI. Biologically relevant default genes were added.
5. Edits the created "*_objdef.rds" and "*_objdimr.rds" files so that UMAP1 or UMAP2 will be displayed.
6. Creates the Shiny app with the specified labels.
7. Automatically generates the "app.R" script necessary for running the app.

03_App

Contains the final Shiny app and runtime configuration.

This directory stores all files necessary to run the app (generated by "makeShinyAppV4.R"). The script to run the app, "app.R", is automatically generated by "makeShinyAppV4.R".  

For SciLifeLab hosting - data files are not included in the github repo (as some files are too large). This directory is kept free of data and data is instead mounted in SciLifeLab. 

All required .rds and .h5 data files must be present in the mounted SciLifeLab directory:

/srv/shiny-server/data/

The app will fail to launch if these files are missing.

The auto-generated scripts "server.R" and "ui.R" were edited after running "makeShinyAppV4.R" to support the following:
1. auto-detect whether the user is launching the app via a local repo or whether the app is being launched through SciLifeLab.
2. toggle heatmap/bubblemap generation for user selected "annotated_celltype" and feature.

Reproducibility

This project uses renv to manage R package dependencies and ensure reproducibility (with renv::init()). The renv.lock file records the exact versions of all packages used. 

To restore the environment:
renv::restore()

This installs all required package versions as recorded in renv.lock. 

The objects necessary for running the app locally are not included in this repo as the file sizes are too large. 

App Maintenance - Docker

To containerize the app Docker was used. Docker version 29.3.1, build c2be9cc was installed for the desktop and a Docker image was created from the project root with the manually generated Dockerfile (edited from SciLifeLab: https://serve.scilifelab.se/docs/application-hosting/shiny/#wiki-toc-step-2-create-a-dockerfile-for-your-app).

A .dockerignore is included to omit data files from the image - the data is instead mounted on SciLifeLab and is pulled at run time.

A GitHub Actions workflow is included to automate Docker image builds and updates.

The image is pushed to the public Docker Hub repo at: docker.io/regenimmuno/limb-shiny-app:latest or $TAG

*** note: the image must remain public for the app to run on SciLifeLab *** 

#!/usr/bin/env bash

# run from the project root (this will only include what is explicitly mentioned in the Dockerfile)
# build image (use --no-cache only if needed)
docker build --platform linux/amd64 -t regenimmuno/limb-shiny-app:v1 .

# check image
docker images -a                                                        

# push to Docker Hub 
docker push regenimmuno/limb-shiny-app:v1

App Maintenance

As long as the Docker image is published publically - the app should continue to run in SciLifeLab. 

To update / maintain the app: 

1. If modifications are made to the original seurat objects or the app running objects (ie. via "Seurat_EditsV2.R" or "makeShinyAppV4.R"): the data mounted in SciLifeLab must be manually swapped for the edited .rds and .h5 files. 
2. If modifications are made to the app running code (ie. "server.R" or "ui.R") or the environment ("renv.lock"): the code changes should be pushed to GitHub. GitHub Actions should automatically update the Docker image and push it to Docker Hub with two tags: one by version and one labeled "latest". In the case this doesn't function properly - one must manually rebuild/push the image as shown below and update the new image path in SciLifeLab.

References

Scripts were modified from the ShinyCell2 documentation and the "EquBAL Explorer" GitHub repo:

https://github.com/Molmed/EquBAL_explorer

https://github.com/the-ouyang-lab/ShinyCell2

Chen, B. J., Lim, Y. Y., Yang, X., Wang, L., Rackham, O. J. L., & Ouyang, J. F. (2025). ShinyCell2: An extended library for simple and sharable visualisation of spatial, peak-based and multi-omic single-cell data (p. 2025.04.22.650045). bioRxiv. https://doi.org/10.1101/2025.04.22.650045

The app is hosted on SciLifeLab. Setup instructions can be found here:
https://serve.scilifelab.se/docs/application-hosting/shiny/