Installation

Asc-Seurat can be installed in two ways:

Docker — recommended for most users. Zero dependency management; every optional feature is bundled.
R package from GitHub — lighter and starts faster if you already work in R and are comfortable managing Bioconductor packages.

Both options run the same Shiny app and produce identical results.

Source code lives at https://github.com/Pereira-Lab-UF/asc_seurat.

Option 1 — Docker (recommended)

Requirements: a recent Docker installation. Nothing else.

docker pull pereiralabbio/asc-seurat:3 && docker run --rm -p 3838:3838 pereiralabbio/asc-seurat:3

Then open http://localhost:3838 in a browser.

Docker containers cannot see arbitrary host paths unless those paths are mounted when the container starts. The easiest pattern is to launch the container from the folder that contains your data and mount that current folder into Asc-Seurat’s data/ directory:

cd "/path/to/folder/that/contains/your/data"
docker run --rm -p 3838:3838 \
  -v "$PWD:/home/ascseurat/data:ro" \
  pereiralabbio/asc-seurat:3

Then enter paths relative to the app workdir, for example data/sample/filtered_feature_bc_matrix. If the mounted folder itself is the 10X matrix directory, enter data/.

If you prefer to paste normal absolute paths from anywhere under your home directory on macOS or Linux, mount your home directory at the same path inside the container:

docker run --rm -p 3838:3838 \
  -v "$HOME:$HOME:ro" \
  pereiralabbio/asc-seurat:3

Then enter the normal absolute path in Asc-Seurat, for example /Users/you/project/sample/filtered_feature_bc_matrix, without wrapping the path in quotes. To expose external drives on macOS, also mount /Volumes:/Volumes:ro. On Windows, mount a folder to a Linux container path such as /home/ascseurat/data and enter data/... in the app.

Option 2 — R package from GitHub

Requires R ≥ 4.3.0 and Rstudio is recommended.

From a terminal, install the system dependencies first. Asc-Seurat installs the R packages automatically, but native packages still need compilers and HDF5 available on the machine.

# Ubuntu/Debian
sudo apt-get install -y build-essential gfortran libhdf5-dev pkg-config

# macOS
xcode-select --install
brew install hdf5 pkg-config
curl -LO https://mac.r-project.org/tools/gfortran-14.2-universal.pkg
sudo installer -pkg gfortran-14.2-universal.pkg -target /

Follow the upstream BPCells R installation instructions if you need more detail on the HDF5 requirement.

Then, from inside an R session, install BPCells before installing Asc-Seurat. BPCells is required by the trajectory stack, and installing it first avoids a known pak failure with GitHub sub-directory packages.

install.packages(c("pak", "remotes"))
remotes::install_github("bnprks/BPCells/r", upgrade = "never")
pak::pkg_install(
  "Pereira-Lab-UF/asc_seurat",
  dependencies = c("Depends", "Imports", "LinkingTo")
)

The pak command installs every R package declared as an app runtime dependency in DESCRIPTION, including PseudotimeDE. It avoids only developer, documentation, and test-only packages. On macOS, PseudotimeDE requires the official R GNU Fortran toolchain above. The error library 'emutls_w' not found means that toolchain is missing or mismatched.

If the GitHub install of BPCells is rate-limited or unavailable, use the BPCells R-universe repository first, then run the Asc-Seurat install:

install.packages("BPCells", repos = c("https://bnprks.r-universe.dev", "https://cloud.r-project.org"))
pak::pkg_install(
  "Pereira-Lab-UF/asc_seurat",
  dependencies = c("Depends", "Imports", "LinkingTo")
)

Then launch the app:

ascseurat::run_app()

Python dependencies for PAGA

Docker users can skip this step — Scanpy is already in the image.

PAGA uses the Python Scanpy stack via reticulate. A one-liner prepares and verifies a managed Python environment:

ascseurat::setup_paga()

Resource notes

Single-cell analysis is memory-intensive. Larger datasets will require more RAM whether you use Docker or the R package. we recommend at least 8 GB for datasets of ~20,000 cells.

Verifying the installation

After launching the app, open the Demo tab in the top navigation. A 2,000-cell subset of the PBMC 3k reference dataset is loaded automatically and you can walk through the full workflow in a few minutes. See Getting started for the step-by-step tour.