Prepare a Seurat object for ShinyCellModular

Takes a Seurat object from single cell experiments and prepares all files needed to run a ShinyCellModular interactive Shiny app. Writes HDF5 counts, ShinyCell config files, optional 3D UMAP, marker genes, and motif data to out_dir.

prepShinyCellModular(
  seurat_obj = NULL,
  seurat_rds = NULL,
  out_dir = "ShinyCellModular_app",
  shiny_title = "ShinyCellModular Intermediate",
  assays_selected = "RNA",
  ident_col = NULL,
  do_variable_features = TRUE,
  do_markers = FALSE,
  markers_file = NULL,
  markers_overwrite = FALSE,
  markers_res_pattern = "res\\.",
  do_umap3d = FALSE,
  umap3d_reductions = c("pca"),
  umap3d_dims = 1:30,
  umap3d_name_suffix = "_umap3d",
  do_counts_h5 = TRUE,
  counts_h5_file = NULL,
  counts_overwrite = TRUE,
  counts_layer = "counts",
  do_make_app = TRUE,
  gene_mapping = TRUE,
  do_motifs = "auto",
  motifs_findmotifs = NULL,
  motifs_overwrite = TRUE,
  fragments_paths = NULL,
  atac_tile_binsize = 500,
  custom_colors = NULL,
  default_genes = NULL,
  install_missing = FALSE,
  verbose = TRUE,
  help = FALSE
)

Arguments

seurat_obj

Seurat object. Alternative to seurat_rds.

seurat_rds

Path to a .rds Seurat object. Alternative to seurat_obj.

out_dir

Output directory. Default: 'Files_ShinyCellModular'.

shiny_title

Title for the Shiny app.

assays_selected

Assay(s) to process. e.g. c('RNA', 'ATAC'). Default: 'RNA'.

ident_col

Column to set as Idents. Default: NULL (uses existing).

do_variable_features

Run FindVariableFeatures before creating the ShinyCell config. Default: TRUE.

do_markers

Compute marker genes with presto. Default: FALSE.

markers_file

Path for output markers parquet file. Default: auto.

markers_overwrite

Overwrite existing markers file. Default: FALSE.

markers_res_pattern

Regex pattern to find resolution columns. Default: 'res\\.'.

do_umap3d

Run 3D UMAP. Default: FALSE.

umap3d_reductions

Reductions to use as input for 3D UMAP. Default: c('pca').

umap3d_dims

Dims to pass to UMAP (auto-capped to available). Default: 1:30.

umap3d_name_suffix

Suffix appended to the 3D UMAP reduction name. Default: '_umap3d'.

do_counts_h5

Write raw counts to HDF5. Default: TRUE.

counts_h5_file

Path for output H5 file. Default: auto.

counts_overwrite

Overwrite existing H5 file. Default: TRUE.

counts_layer

Seurat layer to use for counts. Default: 'counts'.

do_make_app

Run makeShinyApp. Default: TRUE.

gene_mapping

Map gene names in ShinyCell. Default: TRUE.

do_motifs

Extract motifs from ATAC assay. Runs automatically when ATAC is in assays_selected and the motifs slot is populated. Set to FALSE to skip. Default: 'auto'.

motifs_findmotifs

Output of FindMotifs(), adds enrichment scores. Default: NULL.

motifs_overwrite

Overwrite existing motif files. Default: TRUE.

fragments_paths

Optional named list of fragment file path overrides by index. e.g. list('1' = '/path/to/sample1.tsv.gz'). If NULL, paths are copied from the original paths in the object. Default: NULL.

atac_tile_binsize

Bin width in bp for the precomputed genome-wide insertion count matrix used by the Coverage Plot tab. Smaller bins are more precise but make prep slower and the saved matrix bigger. Default: 500.

custom_colors

Named character vector of label -> hex color to override ShinyCell default colors. Extra names not in the data are ignored. Default: NULL.

default_genes

Character vector of gene names to set as defaults in the app (e.g. c('CD4', 'CD8A')). If NULL, ShinyCell picks its own defaults. Default: NULL.

install_missing

Auto-install missing packages. Default: FALSE.

verbose

Print progress messages. Default: TRUE.

help

Print the help message and return. Default: FALSE.

Value

Invisibly returns NULL. Writes output files to out_dir.

#' @section Step by step:

1. Dependency check. Builds a list of required CRAN, Bioconductor, and GitHub-only packages (ShinyCell, ggseqlogo, FlexDotPlot, and presto if do_markers = TRUE; Signac is added automatically if "ATAC" is in assays_selected). Missing packages stop execution with an install hint unless install_missing = TRUE, in which case they are installed automatically.

2. Load the Seurat object. Exactly one of seurat_obj / seurat_rds must resolve to a Seurat object. If both are NULL (and help wasn't explicitly set), help is forced to TRUE and the function prints its help message and returns. Passing a file path to seurat_obj or an in-memory object to seurat_rds triggers a warning() pointing at the likely mistake.

3. Validate assays_selected. Checks every entry exists in Seurat::Assays(seurat_obj); stops with the requested vs. available assay names otherwise.

4. Ensure assay keys exist. For any assay with a missing or empty Key(), sets one automatically (tolower(assay) + "_") so downstream Seurat/Signac calls don't fail.

5. Main loop over assays_selected. For each active_assay (DefaultAssay(seurat_obj) <- active_assay):

   • RNA branch (active_assay == "RNA"): creates out_dir/RNA/, optionally sets Idents() from ident_col, optionally adds 3D UMAP reductions (do_umap3d, skipping any reduction not present with a message), and optionally computes markers per resolution column matched by markers_res_pattern using presto::wilcoxauc (skipping resolutions with fewer than 2 groups), writing the combined table to markers_file via arrow::write_parquet().

   • ATAC branch (active_assay == "ATAC"): creates out_dir/ATAC/, resolves whether to run motif extraction from do_motifs ("auto" checks the @motifs slot; otherwise isTRUE(do_motifs)), extracting PWMs and names into sc1motifs.rds and sc1motifs_meta.parquet if so, optionally joined with motifs_findmotifs enrichment scores. Always extracts static ATAC objects (sc1annotation.rds, sc1peaks.rds, sc1links.rds, each skipped individually with a message if the slot is empty), and copies fragment files into out_dir/ATAC/fragments/index<N>/, using fragments_paths overrides for any file missing from the object's original path. Writes sc1fragmentpaths.rds.

   • All assays: if do_make_app = TRUE, optionally runs FindVariableFeatures(), then ShinyCell::createConfig() and ShinyCell::makeShinyApp() into out_dir/<assay>/. If custom_colors is supplied, patches matching factor-level colours into the sc1conf.rds that makeShinyApp() just wrote (since makeShinyApp() ignores any pre-patched config passed in). If do_counts_h5 = TRUE, writes the sparse counts matrix (CSC format: i, p, x, dims, genes, cells) to out_dir/<assay>/sc1counts.h5 via hdf5r.

Notes

• custom_colors passed via source("colors.R") returns a list, not a named vector. The function detects this, extracts $value automatically, and warns you to pass custom_colors = source("colors.R")$value directly next time.

• Fragment files that can't be found anywhere (neither the original path nor a fragments_paths override) are reported with a ready-to-paste fragments_paths = list(...) snippet in the message.

• install_missing = TRUE also runs setRepositories(ind = 1:3) before install.packages() so Bioconductor dependencies (e.g. for Signac) resolve correctly.

Examples

if (FALSE) { # \dontrun{
prepShinyCellModular(
  seurat_rds = "seurat_object.rds",
  out_dir    = "my_app_files",
  do_umap3d  = TRUE,
  do_markers = TRUE
)
} # }