biopipen 0.23.8__py3-none-any.whl → 0.24.0__py3-none-any.whl

biopipen/__init__.py

@@ -1 +1 @@
-__version__ = "0.23.8"
+__version__ = "0.24.0"

biopipen/core/proc.py

@@ -25,3 +25,10 @@ class Proc(PipenProc):
         "filters": {**FILTERS, **filtermanager.filters},
         "search_paths": SEARCH_PATHS + [str(REPORT_DIR)],
     }
+
+    plugin_opts = {
+        "poplog_pattern": (
+            r"^(?P<level>INFO|WARN|WARNING|CRITICAL|ERROR|DEBUG?)\s*"
+            r"\[\d+-\d+-\d+ \d+:\d+:\d+\] (?P<message>.*)$"
+        )
+    }

biopipen/ns/cellranger.py

@@ -35,7 +35,7 @@ class CellRangerCount(Proc):
             {%- set fastqs = fastqs[0] | glob: "*.fastq.gz" -%}
         {%- endif -%}
         {%- set sample = commonprefix(*fastqs) |
-            regex_replace: "_L\\d+_$", "" |
+            regex_replace: "_L\\d+_?$", "" |
             regex_replace: "_S\\d+$", "" -%}
         {{- sample -}}
     """
@@ -84,7 +84,7 @@ class CellRangerVdj(Proc):
             {%- set fastqs = fastqs[0] | glob: "*.fastq.gz" -%}
         {%- endif -%}
         {%- set sample = commonprefix(*fastqs) |
-            regex_replace: "_L\\d+_$", "" |
+            regex_replace: "_L\\d+_?$", "" |
             regex_replace: "_S\\d+$", "" -%}
         {{- sample -}}
     """

biopipen/ns/scrna.py

@@ -278,18 +278,14 @@ class SeuratClustering(Proc):
                 The results will be saved in `seurat_clusters_<resolution>`.
                 The final resolution will be used to define the clusters at `seurat_clusters`.
             - <more>: See <https://satijalab.org/seurat/reference/findclusters>
-        cache (type=auto): Whether to cache the seurat object with cluster information.
+        cache (type=auto): Whether to cache the information at different steps.
             If `True`, the seurat object will be cached in the job output directory, which will be not cleaned up when job is rerunning.
-            The cached seurat object will be saved as `<signature>.cached.RDS` file, where `<signature>` is the signature determined by
+            The cached seurat object will be saved as `<signature>.<kind>.RDS` file, where `<signature>` is the signature determined by
             the input and envs of the process.
-            See -
-            * <https://github.com/satijalab/seurat/issues/7849>
-            * <https://github.com/satijalab/seurat/issues/5358> and
-            * <https://github.com/satijalab/seurat/issues/6748> for more details.
+            See <https://github.com/satijalab/seurat/issues/7849>, <https://github.com/satijalab/seurat/issues/5358> and
+            <https://github.com/satijalab/seurat/issues/6748> for more details also about reproducibility issues.
             To not use the cached seurat object, you can either set `cache` to `False` or delete the cached file at
-            `<signature>.cached.RDS` in the cache directory.
-            If `True`, the cache directory is `.pipen/<Pipeline>/SeuratClustering/0/output/`
-            You can also specify customized directory to save the cached seurat object by setting `cache` to the directory path.
+            `<signature>.RDS` in the cache directory.
 
     Requires:
         r-seurat:
@@ -309,7 +305,7 @@ class SeuratClustering(Proc):
         "RunUMAP": {"dims": 30},
         "FindNeighbors": {},
         "FindClusters": {"resolution": 0.8},
-        "cache": False,
+        "cache": config.path.tmpdir,
     }
     script = "file://../scripts/scrna/SeuratClustering.R"
 
@@ -361,18 +357,14 @@ class SeuratSubClustering(Proc):
                 The results will be saved in `<casename>_<resolution>`.
                 The final resolution will be used to define the clusters at `<casename>`.
             - <more>: See <https://satijalab.org/seurat/reference/findclusters>
-        cache (type=auto): Whether to cache the seurat object with cluster information.
+        cache (type=auto): Whether to cache the information at different steps.
             If `True`, the seurat object will be cached in the job output directory, which will be not cleaned up when job is rerunning.
-            The cached seurat object will be saved as `<signature>.cached.RDS` file, where `<signature>` is the signature determined by
+            The cached seurat object will be saved as `<signature>.<kind>.RDS` file, where `<signature>` is the signature determined by
             the input and envs of the process.
-            See -
-            * <https://github.com/satijalab/seurat/issues/7849>
-            * <https://github.com/satijalab/seurat/issues/5358> and
-            * <https://github.com/satijalab/seurat/issues/6748> for more details.
+            See <https://github.com/satijalab/seurat/issues/7849>, <https://github.com/satijalab/seurat/issues/5358> and
+            <https://github.com/satijalab/seurat/issues/6748> for more details also about reproducibility issues.
             To not use the cached seurat object, you can either set `cache` to `False` or delete the cached file at
-            `<signature>.cached.RDS` in the cache directory.
-            If `True`, the cache directory is `.pipen/<Pipeline>/SeuratClustering/0/output/`
-            You can also specify customized directory to save the cached seurat object by setting `cache` to the directory path.
+            `<signature>.RDS` in the cache directory.
         cases (type=json): The cases to perform subclustering.
             Keys are the names of the cases and values are the dicts inherited from `envs` except `mutaters` and `cache`.
             If empty, a case with name `subcluster` will be created with default parameters.
@@ -387,7 +379,7 @@ class SeuratSubClustering(Proc):
         "RunUMAP": {"dims": 30},
         "FindNeighbors": {},
         "FindClusters": {"resolution": 0.8},
-        "cache": False,
+        "cache": config.path.tmpdir,
         "cases": {"subcluster": {}},
     }
     script = "file://../scripts/scrna/SeuratSubClustering.R"
@@ -2002,4 +1994,5 @@ class MetaMarkers(Proc):
     plugin_opts = {
         "report": "file://../reports/scrna/MetaMarkers.svelte",
         "report_paging": 8,
+        "poplog_max": 15,
     }

biopipen/ns/tcr.py

@@ -563,12 +563,13 @@ class Immunarch(Proc):
                     A Gini coefficient of one (or 100 percents) expresses maximal inequality among values (for example where only one person has all the income).
                 - d50: The D50 index.
                     It is the number of types that are needed to cover 50%% of the total abundance.
-                - dxx: The Dxx index.
-                    It is the number of types that are needed to cover xx%% of the total abundance.
-                    The percentage should be specified in the `args` argument using `perc` key.
                 - raref: Species richness from the results of sampling through extrapolation.
             - by: The variables (column names) to group samples.
                 Multiple columns should be separated by `,`.
+            - plot_type (choice): The type of the plot, works when `by` is specified.
+                Not working for `raref`.
+                - box: Boxplot
+                - bar: Barplot with error bars
             - subset: Subset the data before calculating the clonotype volumes.
                 The whole data will be expanded to cell level, and then subsetted.
                 Clone sizes will be re-calculated based on the subsetted data.
@@ -789,9 +790,9 @@ class Immunarch(Proc):
         },
         # Diversity
         "divs": {
-            "filter": None,
             "method": "gini",
             "by": None,
+            "plot_type": "bar",
             "args": {},
             "order": [],
             "test": {
@@ -805,8 +806,8 @@ class Immunarch(Proc):
             "align_y": False,
             "log": False,
             "devpars": {
-                "width": 1000,
-                "height": 1000,
+                "width": 800,
+                "height": 800,
                 "res": 100,
             },
             "subset": None,
@@ -851,6 +852,7 @@ class Immunarch(Proc):
     plugin_opts = {
         "report": "file://../reports/tcr/Immunarch.svelte",
         "report_paging": 3,
+        "poplog_max": 999,
     }
 
 

biopipen/scripts/scrna/SeuratClustering.R

@@ -1,4 +1,5 @@
 source("{{biopipen_dir}}/utils/misc.R")
+source("{{biopipen_dir}}/utils/caching.R")
 
 library(Seurat)
 library(future)
@@ -35,80 +36,100 @@ envs$FindNeighbors <- .expand_dims(envs$FindNeighbors)
 log_info("Reading Seurat object ...")
 sobj <- readRDS(srtfile)
 
-if (isTRUE(envs$cache)) {
-    envs$cache <- joboutdir
+if (isTRUE(envs$cache)) { envs$cache <- joboutdir }
+if (length(envs$cache) > 1) {
+    log_warn("Multiple cache directories (envs.cache) detected, using the first one.")
+    envs$cache <- envs$cache[1]
 }
-
-if (is.character(envs$cache) && nchar(envs$cache) > 0) {
-    log_info("Obtainning the signature ...")
-    envs2 <- envs
-    envs2$ncores <- NULL
-    sig <- c(
-        capture.output(str(sobj)),
-        "\n\n-------------------\n\n",
-        capture.output(str(envs2)),
-        "\n"
-    )
-    digested_sig <- digest::digest(sig, algo = "md5")
-    cached_file <- file.path(envs$cache, paste0(digested_sig, ".cached.RDS"))
-    if (file.exists(cached_file)) {
-        log_info("Using cached results {cached_file}")
-        # copy cached file to rdsfile
-        file.copy(cached_file, rdsfile, copy.date = TRUE)
-        quit()
-    } else {
-        log_info("Cached results not found, logging the current and cached signatures.")
-        log_info("- Current signature: {digested_sig}")
-        # print(sig)
-        # sigfiles <- Sys.glob(file.path(envs$cache, "*.signature.txt"))
-        # for (sigfile in sigfiles) {
-        #     log_info("- Found cached signature file: {sigfile}")
-        #     cached_sig <- readLines(sigfile)
-        #     log_info("- Cached signature:")
-        #     print(cached_sig)
-        # }
-        writeLines(sig, file.path(envs$cache, paste0(digested_sig, ".signature.txt")))
-    }
+sobj_sig <- capture.output(str(sobj))
+dig_sig <- digest::digest(sobj_sig, algo = "md5")
+dig_sig <- substr(dig_sig, 1, 8)
+cache_dir <- NULL
+if (is.character(envs$cache)) {
+    cache_dir <- file.path(envs$cache, paste0(dig_sig, ".seurat_cache"))
+    dir.create(cache_dir, recursive = TRUE, showWarnings = FALSE)
+    writeLines(sobj_sig, file.path(cache_dir, "signature.txt"))
 }
 
 if (length(envs$ScaleData) > 0) {
     if (DefaultAssay(sobj) == "SCT") {
         stop("SCT assay detected, but ScaleData is specified. Use SCTransform instead.")
     }
-    log_info("Running ScaleData ...")
-    envs$ScaleData$object <- sobj
-    sobj <- do_call(ScaleData, envs$ScaleData)
+    cached <- get_cached(envs$ScaleData, "ScaleData", cache_dir)
+    if (is.null(cached$data)) {
+        log_info("Running ScaleData ...")
+        envs$ScaleData$object <- sobj
+        sobj <- do_call(ScaleData, envs$ScaleData)
+        cached$data <- list(assay = sobj@assays$RNA, commands = sobj@commands)
+        save_to_cache(cached, "ScaleData", cache_dir)
+    } else {
+        log_info("Loading cached ScaleData ...")
+        sobj@assays$RNA <- cached$data$assay
+        sobj@commands <- cached$data$commands
+        DefaultAssay(sobj) <- "RNA"
+    }
 } else if (length(envs$SCTransform) > 0) {
     if (DefaultAssay(sobj) != "SCT") {
         stop("SCT assay not detected, but SCTransform is specified. Use ScaleData instead.")
     }
-    log_info("Running SCTransform ...")
-    envs$SCTransform$object <- sobj
-    sobj <- do_call(SCTransform, envs$SCTransform)
+    cached <- get_cached(envs$SCTransform, "SCTransform", cache_dir)
+    asssay <- envs$SCTransform$new.assay.name %||% "SCT"
+    if (is.null(cached$data)) {
+        log_info("Running SCTransform ...")
+        envs$SCTransform$object <- sobj
+        sobj <- do_call(SCTransform, envs$SCTransform)
+        cached$data <- list(assay = sobj@assays$SCT, commands = sobj@commands)
+        save_to_cache(cached, "SCTransform", cache_dir)
+    } else {
+        log_info("Loading cached SCTransform ...")
+        sobj@assays[[assay]] <- cached$data$assay
+        sobj@commands <- cached$data$commands
+        DefaultAssay(sobj) <- assay
+    }
 }
 
-log_info("Running RunUMAP ...")
-umap_args <- list_setdefault(
-    envs$RunUMAP,
-    object = sobj,
-    dims = 1:30,
-    reduction = sobj@misc$integrated_new_reduction %||% "pca"
-)
-umap_args$dims <- 1:min(max(umap_args$dims), ncol(sobj) - 1)
-sobj <- do_call(RunUMAP, umap_args)
-
-log_info("Running FindNeighbors ...")
-envs$FindNeighbors$object <- sobj
-if (is.null(envs$FindNeighbors$reduction)) {
-    envs$FindNeighbors$reduction <- sobj@misc$integrated_new_reduction %||% "pca"
+cached <- get_cached(envs$RunUMAP, "RunUMAP", cache_dir)
+reduc_name <- envs$RunUMAP$reduction.name %||% "umap"
+if (is.null(cached$data)) {
+    log_info("Running RunUMAP ...")
+    umap_args <- list_setdefault(
+        envs$RunUMAP,
+        object = sobj,
+        dims = 1:30,
+        reduction = sobj@misc$integrated_new_reduction %||% "pca"
+    )
+    ncells <- ncol(sobj)
+    umap_args$dims <- 1:min(max(umap_args$dims), ncells - 1)
+    umap_method <- envs$RunUMAP$umap.method %||% "uwot"
+    if (umap_method == "uwot" && is.null(envs$RunUMAP$n.neighbors)) {
+        # https://github.com/satijalab/seurat/issues/4312
+        umap_args$n.neighbors <- min(ncells - 1, 30)
+    }
+    sobj <- do_call(RunUMAP, umap_args)
+    cached$data <- list(reduc = sobj@reductions[[reduc_name]], commands = sobj@commands)
+    save_to_cache(cached, "RunUMAP", cache_dir)
+} else {
+    log_info("Loading cached RunUMAP ...")
+    sobj@reductions[[reduc_name]] <- cached$data$reduc
+    sobj@commands <- cached$data$commands
 }
-sobj <- do_call(FindNeighbors, envs$FindNeighbors)
 
-log_info("Running FindClusters ...")
-if (is.null(envs$FindClusters$random.seed)) {
-    envs$FindClusters$random.seed <- 8525
+cached <- get_cached(envs$FindNeighbors, "FindNeighbors", cache_dir)
+if (is.null(cached$data)) {
+    log_info("Running FindNeighbors ...")
+    envs$FindNeighbors$object <- sobj
+    envs$FindNeighbors$reduction <- sobj@misc$integrated_new_reduction %||% "pca"
+    sobj <- do_call(FindNeighbors, envs$FindNeighbors)
+    cached$data <- list(graphs = sobj@graphs, commands = sobj@commands)
+    save_to_cache(cached, "FindNeighbors", cache_dir)
+} else {
+    log_info("Loading cached FindNeighbors ...")
+    sobj@graphs <- cached$data$graphs
+    sobj@commands <- cached$data$commands
 }
-resolution <- envs$FindClusters$resolution
+
+envs$FindClusters$random.seed <- envs$FindClusters$random.seed %||% 8525
+resolution <- envs$FindClusters$resolution %||% 0.8
 if (is.character(resolution)) {
     if (grepl(",", resolution)) {
         resolution <- as.numeric(trimws(unlist(strsplit(resolution, ","))))
@@ -116,42 +137,38 @@ if (is.character(resolution)) {
         resolution <- as.numeric(resolution)
     }
 }
-if (is.null(resolution) || length(resolution) == 1) {
-    envs$FindClusters$resolution <- resolution
-    envs$FindClusters$object <- sobj
-    sobj <- do_call(FindClusters, envs$FindClusters)
-    levels(sobj$seurat_clusters) <- paste0("c", as.numeric(levels(sobj$seurat_clusters)) + 1)
-    Idents(sobj) <- "seurat_clusters"
-    ident_table <- table(sobj$seurat_clusters)
-    log_info("- Found {length(ident_table)} clusters:")
-    print(ident_table)
-} else {
-    log_info("- Multiple resolutions detected ...")
-    res_key <- NULL
-    for (res in resolution) {
-        findclusters_args <- envs$FindClusters
-        findclusters_args$resolution <- res
-        findclusters_args$object <- sobj
-        sobj <- do_call(FindClusters, findclusters_args)
+
+for (res in resolution) {
+    envs$FindClusters$resolution <- res
+    cached <- get_cached(envs$FindClusters, paste0("FindClusters_", res), cache_dir)
+    res_key <- paste0("seurat_clusters_", res)
+    if (is.null(cached$data)) {
+        log_info("Running FindClusters at resolution: {res} ...")
+        envs$FindClusters$object <- sobj
+        sobj <- do_call(FindClusters, envs$FindClusters)
         levels(sobj$seurat_clusters) <- paste0("c", as.numeric(levels(sobj$seurat_clusters)) + 1)
-        res_key <- paste0("seurat_clusters_", res)
         sobj[[res_key]] <- sobj$seurat_clusters
-        ident_table <- table(sobj[[res_key]])
-        log_info("- Found {length(ident_table)} at resolution: {res}:")
-        print(ident_table)
+        Idents(sobj) <- "seurat_clusters"
+        cached$data <- list(clusters = sobj$seurat_clusters, commands = sobj@commands)
+        save_to_cache(cached, paste0("FindClusters_", res), cache_dir)
+    } else {
+        log_info("Loading cached FindClusters at resolution: {res} ...")
+        sobj@commands <- cached$data$commands
+        sobj[[res_key]] <- cached$data$clusters
+        sobj$seurat_clusters <- cached$data$clusters
+        Idents(sobj) <- "seurat_clusters"
     }
+    ident_table <- table(Idents(sobj))
+    log_info("- Found {length(ident_table)} clusters")
+    print(ident_table)
+    cat("\n")
 }
 
 if (DefaultAssay(sobj) == "SCT") {
-    # https://github.com/satijalab/seurat/issues/6968
+        # https://github.com/satijalab/seurat/issues/6968
     log_info("Running PrepSCTFindMarkers ...")
     sobj <- PrepSCTFindMarkers(sobj)
 }
 
 log_info("Saving results ...")
 saveRDS(sobj, file = rdsfile)
-
-if (is.character(envs$cache) && nchar(envs$cache) > 0) {
-    log_info("Caching results ...")
-    file.copy(rdsfile, cached_file, overwrite = TRUE)
-}

biopipen/scripts/scrna/SeuratPreparing.R

@@ -301,26 +301,31 @@ log_info("Performing transformation/scaling ...")
 if (envs$use_sct) {
     log_info("- Running SCTransform ...")
     SCTransformArgs <- envs$SCTransform
-    log_info("  SCTransform: {.formatArgs(SCTransformArgs)}")
+    # log to stdout but don't populate it to running log
+    print("  SCTransform: {.formatArgs(SCTransformArgs)}")
+    log_debug("  SCTransform: {.formatArgs(SCTransformArgs)}")
     SCTransformArgs$object <- sobj
     sobj <- do_call(SCTransform, SCTransformArgs)
     # Default is to use the SCT assay
 } else {
     log_info("- Running NormalizeData ...")
     NormalizeDataArgs <- envs$NormalizeData
-    log_info("  NormalizeData: {.formatArgs(NormalizeDataArgs)}")
+    print("  NormalizeData: {.formatArgs(NormalizeDataArgs)}")
+    log_debug("  NormalizeData: {.formatArgs(NormalizeDataArgs)}")
     NormalizeDataArgs$object <- sobj
     sobj <- do_call(NormalizeData, NormalizeDataArgs)
 
     log_info("- Running FindVariableFeatures ...")
     FindVariableFeaturesArgs <- envs$FindVariableFeatures
-    log_info("  FindVariableFeatures: {.formatArgs(FindVariableFeaturesArgs)}")
+    print("  FindVariableFeatures: {.formatArgs(FindVariableFeaturesArgs)}")
+    log_debug("  FindVariableFeatures: {.formatArgs(FindVariableFeaturesArgs)}")
     FindVariableFeaturesArgs$object <- sobj
     sobj <- do_call(FindVariableFeatures, FindVariableFeaturesArgs)
 
     log_info("- Running ScaleData ...")
     ScaleDataArgs <- envs$ScaleData
-    log_info("  ScaleData: {.formatArgs(ScaleDataArgs)}")
+    print("  ScaleData: {.formatArgs(ScaleDataArgs)}")
+    log_debug("  ScaleData: {.formatArgs(ScaleDataArgs)}")
     ScaleDataArgs$object <- sobj
     sobj <- do_call(ScaleData, ScaleDataArgs)
 }
@@ -328,7 +333,8 @@ if (envs$use_sct) {
 log_info("- Running RunPCA ...")
 RunPCAArgs <- envs$RunPCA
 RunPCAArgs$npcs <- if (is.null(RunPCAArgs$npcs)) { 50 } else { min(RunPCAArgs$npcs, ncol(sobj) - 1) }
-log_info("  RunPCA: {.formatArgs(RunPCAArgs)}")
+print("  RunPCA: {.formatArgs(RunPCAArgs)}")
+log_debug("  RunPCA: {.formatArgs(RunPCAArgs)}")
 RunPCAArgs$object <- sobj
 sobj <- do_call(RunPCA, RunPCAArgs)
 
@@ -361,7 +367,8 @@ if (!envs$no_integration) {
     if (is.null(IntegrateLayersArgs$new.reduction)) {
         IntegrateLayersArgs$new.reduction <- new_reductions[[method]]
     }
-    log_info("  IntegrateLayers: {.formatArgs(IntegrateLayersArgs)}")
+    print("  IntegrateLayers: {.formatArgs(IntegrateLayersArgs)}")
+    log_debug("  IntegrateLayers: {.formatArgs(IntegrateLayersArgs)}")
     IntegrateLayersArgs$object <- sobj
     sobj <- do_call(IntegrateLayers, IntegrateLayersArgs)
     # Save it for dimension reduction plots

biopipen/scripts/scrna/SeuratSubClustering.R

@@ -1,4 +1,5 @@
 source("{{biopipen_dir}}/utils/misc.R")
+source("{{biopipen_dir}}/utils/caching.R")
 
 library(Seurat)
 library(future)
@@ -33,40 +34,10 @@ envs$FindNeighbors <- .expand_dims(envs$FindNeighbors)
 log_info("Reading Seurat object ...")
 srtobj <- readRDS(srtfile)
 
-if (isTRUE(envs$cache)) {
-    envs$cache <- joboutdir
-}
-
-if (is.character(envs$cache) && nchar(envs$cache) > 0) {
-    log_info("Obtainning the signature ...")
-    envs2 <- envs
-    envs2$ncores <- NULL
-    sig <- c(
-        capture.output(str(srtobj)),
-        "\n\n-------------------\n\n",
-        capture.output(str(envs2)),
-        "\n"
-    )
-    digested_sig <- digest::digest(sig, algo = "md5")
-    cached_file <- file.path(envs$cache, paste0(digested_sig, ".cached.RDS"))
-    if (file.exists(cached_file)) {
-        log_info("Using cached results {cached_file}")
-        # copy cached file to rdsfile
-        file.copy(cached_file, rdsfile, copy.date = TRUE)
-        quit()
-    } else {
-        log_info("Cached results not found.")
-        log_info("- Current signature: {digested_sig}")
-        # print(sig)
-        # sigfiles <- Sys.glob(file.path(envs$cache, "*.signature.txt"))
-        # for (sigfile in sigfiles) {
-        #     log_info("- Found cached signature file: {sigfile}")
-        #     cached_sig <- readLines(sigfile)
-        #     log_info("- Cached signature:")
-        #     print(cached_sig)
-        # }
-        writeLines(sig, file.path(envs$cache, paste0(digested_sig, ".signature.txt")))
-    }
+if (isTRUE(envs$cache)) { envs$cache <- joboutdir }
+if (length(envs$cache) > 1) {
+    log_warn("Multiple cache directories (envs.cache) detected, using the first one.")
+    envs$cache <- envs$cache[1]
 }
 
 if (!is.null(envs$mutaters) && length(envs$mutaters) > 0) {
@@ -102,30 +73,66 @@ for (key in names(envs$cases)) {
     }
 
     log_info("- Subsetting ...")
-    sobj <- srtobj %>% filter(!!parse_expr(case$subset))
-
-    log_info("- Running RunUMAP ...")
-    umap_args <- list_setdefault(
-        case$RunUMAP,
-        object = sobj,
-        dims = 1:30,
-        reduction = sobj@misc$integrated_new_reduction %||% "pca"
-    )
-    umap_args$dims <- 1:min(max(umap_args$dims), ncol(sobj) - 1)
-    sobj <- do_call(RunUMAP, umap_args)
-
-    log_info("- Running FindNeighbors ...")
-    case$FindNeighbors$object <- sobj
-    if (is.null(case$FindNeighbors$reduction)) {
-        case$FindNeighbors$reduction <- sobj@misc$integrated_new_reduction %||% "pca"
+    sobj <- tryCatch({
+        srtobj %>% filter(!!parse_expr(case$subset))
+    }, error = function(e) {
+        stop(paste0("  Error in subset: ", e$message))
+    })
+    sobj_sig <- capture.output(str(sobj))
+    dig_sig <- digest::digest(sobj_sig, algo = "md5")
+    dig_sig <- substr(dig_sig, 1, 8)
+    cache_dir <- NULL
+    if (is.character(envs$cache)) {
+        cache_dir <- file.path(envs$cache, paste0(dig_sig, ".seurat_cache"))
+        dir.create(cache_dir, recursive = TRUE, showWarnings = FALSE)
+        writeLines(sobj_sig, file.path(cache_dir, "signature.txt"))
     }
-    sobj <- do_call(FindNeighbors, case$FindNeighbors)
 
-    log_info("- Running FindClusters ...")
-    if (is.null(case$FindClusters$random.seed)) {
-        case$FindClusters$random.seed <- 8525
+    cached <- get_cached(case$RunUMAP, "RunUMAP", cache_dir)
+    reduc_name <- case$RunUMAP$reduction.name %||% "umap"
+    if (is.null(cached$data)) {
+        log_info("- Running RunUMAP ...")
+        umap_args <- list_setdefault(
+            case$RunUMAP,
+            object = sobj,
+            dims = 1:30,
+            reduction = sobj@misc$integrated_new_reduction %||% "pca"
+        )
+        ncells <- ncol(sobj)
+        umap_args$dims <- 1:min(max(umap_args$dims), ncells - 1)
+        umap_method <- case$RunUMAP$umap.method %||% "uwot"
+        if (umap_method == "uwot" && is.null(case$RunUMAP$n.neighbors)) {
+            # https://github.com/satijalab/seurat/issues/4312
+            umap_args$n.neighbors <- min(ncells - 1, 30)
+        }
+        sobj <- do_call(RunUMAP, umap_args)
+        cached$data <- list(reduc = sobj@reductions[[reduc_name]], commands = sobj@commands)
+        save_to_cache(cached, "RunUMAP", cache_dir)
+    } else {
+        log_info("- Loading cached RunUMAP ...")
+        sobj@reductions[[reduc_name]] <- cached$data$reduc
+        sobj@commands <- cached$data$commands
+    }
+    reduc <- cached$data$reduc
+
+    cached <- get_cached(case$FindNeighbors, "FindNeighbors", cache_dir)
+    if (is.null(cached$data)) {
+        log_info("- Running FindNeighbors ...")
+        case$FindNeighbors$object <- sobj
+        if (is.null(case$FindNeighbors$reduction)) {
+            case$FindNeighbors$reduction <- sobj@misc$integrated_new_reduction %||% "pca"
+        }
+        sobj <- do_call(FindNeighbors, case$FindNeighbors)
+        cached$data <- list(graphs = sobj@graphs, commands = sobj@commands)
+        save_to_cache(cached, "FindNeighbors", cache_dir)
+    } else {
+        log_info("- Loading cached FindNeighbors ...")
+        sobj@graphs <- cached$data$graphs
+        sobj@commands <- cached$data$commands
     }
-    resolution <- case$FindClusters$resolution
+
+    case$FindClusters$random.seed <- case$FindClusters$random.seed %||% 8525
+    resolution <- case$FindClusters$resolution %||% 0.8
     if (is.character(resolution)) {
         if (grepl(",", resolution)) {
             resolution <- as.numeric(trimws(unlist(strsplit(resolution, ","))))
@@ -133,53 +140,30 @@ for (key in names(envs$cases)) {
             resolution <- as.numeric(resolution)
         }
     }
-    if (is.null(resolution) || length(resolution) == 1) {
-        case$FindClusters$resolution <- resolution
-        case$FindClusters$object <- sobj
-        sobj <- do_call(FindClusters, case$FindClusters)
-        levels(sobj$seurat_clusters) <- paste0("s", as.numeric(levels(sobj$seurat_clusters)) + 1)
-        Idents(sobj) <- "seurat_clusters"
-        sobj[[key]] <- sobj$seurat_clusters
-        ident_table <- table(sobj[[key]])
-        log_info("- Found {length(ident_table)} clusters:")
-        print(ident_table)
-        cat("\n")
-
-        log_info("- Updating meta.data with subclusters...")
-        srtobj <- AddMetaData(srtobj, metadata = sobj@meta.data[, key, drop = FALSE])
-        srtobj[[paste0("sub_umap_", key)]] <- sobj@reductions$umap
-    } else {
-        log_info("- Multiple resolutions detected ...")
-        log_info("")
-        metadata <- NULL
-        for (res in resolution) {
-            findclusters_args <- case$FindClusters
-            findclusters_args$resolution <- res
-            findclusters_args$object <- sobj
-            sobj1 <- do_call(FindClusters, findclusters_args)
-            res_key <- paste0(key, "_", res)
+    for (res in resolution) {
+        case$FindClusters$resolution <- res
+        cached <- get_cached(case$FindClusters, paste0("FindClusters_", res), cache_dir)
+        res_key <- paste0("seurat_clusters_", res)
+        if (is.null(cached$data)) {
+            log_info("- Running FindClusters at resolution: {res} ...")
+            case$FindClusters$object <- sobj
+            sobj1 <- do_call(FindClusters, case$FindClusters)
             levels(sobj1$seurat_clusters) <- paste0("s", as.numeric(levels(sobj1$seurat_clusters)) + 1)
-            Idents(sobj1) <- "seurat_clusters"
             sobj1[[res_key]] <- sobj1$seurat_clusters
-            ident_table <- table(sobj1[[res_key]])
-            log_info("- Found {length(ident_table)} at resolution: {res}:")
-            print(ident_table)
-            cat("\n")
-
-            log_info("- Updating meta.data with subclusters...")
-            metadata <- sobj1@meta.data[, res_key, drop = FALSE]
-            srtobj <- AddMetaData(srtobj, metadata = metadata)
-            srtobj[[paste0("sub_umap_", res_key)]] <- sobj1@reductions$umap
+            cached$data <- sobj1@meta.data[, res_key, drop = FALSE]
+            save_to_cache(cached, paste0("FindClusters_", res), cache_dir)
+        } else {
+            log_info("- Using cached FindClusters at resolution: {res} ...")
         }
-        srtobj <- AddMetaData(srtobj, metadata = metadata, col.name = key)
-        srtobj[[paste0("sub_umap_", key)]] <- sobj1@reductions$umap
+        ident_table <- table(cached$data[[res_key]])
+        log_info("  Found {length(ident_table)} clusters")
+        print(ident_table)
+        cat("\n")
     }
+    log_info("- Updating meta.data with subclusters...")
+    srtobj <- AddMetaData(srtobj, metadata = cached$data, col.name = key)
+    srtobj[[paste0("sub_umap_", key)]] <- reduc
 }
 
 log_info("Saving results ...")
 saveRDS(srtobj, file = rdsfile)
-
-if (is.character(envs$cache) && nchar(envs$cache) > 0) {
-    log_info("Caching results to {cached_file} ...")
-    invisible(file.copy(rdsfile, cached_file, overwrite = TRUE))
-}