@@ -177,6 +177,8 @@ export(runMNNCorrect)

 export(runModelGeneVar)

 export(runNormalization)

 export(runPerCellQC)

+export(runQuickTSNE)

+export(runQuickUMAP)

 export(runSCANORAMA)

 export(runSCMerge)

 export(runScDblFinder)

@@ -200,6 +202,8 @@ export(runSoupX)

 export(runTSCAN)

 export(runTSCANClusterDEAnalysis)

 export(runTSCANDEG)

+export(runTSNE)

+export(runUMAP)

 export(runVAM)

 export(runWilcox)

 export(runZINBWaVE)

@@ -242,6 +246,7 @@ import(DropletUtils)

 import(GSVAdata)

 import(SingleCellExperiment)

 import(fishpond)

+importFrom(BiocParallel,SerialParam)

 importFrom(S4Vectors,"metadata<-")

 importFrom(S4Vectors,metadata)

 importFrom(SingleCellExperiment,"counts<-")

@@ -1,4 +1,5 @@

 #' @title Stores and returns table of SCTK QC outputs to metadata.

+#' @rdname getSampleSummaryStatsTable

 #' @description  Stores and returns table of QC metrics generated from

 #'  QC algorithms within the metadata slot of the SingleCellExperiment object.

 #' @param inSCE Input \linkS4class{SingleCellExperiment} object with saved

@@ -7,8 +8,10 @@

 #' that stores the stats table within the metadata of the

 #' SingleCellExperiment object. Required.

 #' @param ... Other arguments passed to the function. 

-#' @return A matrix/array object. Contains a summary table for QC statistics

-#' generated from SingleCellTK.

+#' @return For \code{getSampleSummaryStatsTable}, A matrix/array object. 

+#' Contains a summary table for QC statistics generated from SingleCellTK. For

+#' \code{setSampleSummaryStatsTable<-}, A SingleCellExperiment object where the 

+#' summary table is updated in the \code{metadata} slot.

 #' @examples

 #' data(scExample, package = "singleCellTK")

 #' sce <- subsetSCECols(sce, colData = "type != 'EmptyDroplet'")

@@ -17,18 +20,13 @@

 #' @export

 setGeneric("getSampleSummaryStatsTable", function(inSCE, statsName, ...) standardGeneric("getSampleSummaryStatsTable"))

-#' @title Setter function which stores table of SCTK QC outputs to metadata.

-#' @description  Stores table of QC metrics generated from

-#'  QC algorithms within the metadata slot of the SingleCellExperiment object.

-#' @param inSCE Input \linkS4class{SingleCellExperiment} object with saved

-#' \link{assay} data and/or \link{colData} data. Required.

-#' @param value The sample summary table of SCTK QC outputs 

-#' @param ... Other arguments passed to the function. 

-#' @return A SingleCellExperiment object which contains a summary table for QC statistics

-#' generated from SingleCellTK.

-setGeneric("setSampleSummaryStatsTable<-", function(inSCE, ..., value) standardGeneric("setSampleSummaryStatsTable<-"))

+#' @rdname getSampleSummaryStatsTable

+#' @param value The summary table for QC statistics generated from SingleCellTK

+#' to be added to the SCE object.

+setGeneric("setSampleSummaryStatsTable<-", function(inSCE, statsName, ..., value) standardGeneric("setSampleSummaryStatsTable<-"))

 #' @title Lists the table of SCTK QC outputs stored within the metadata.

+#' @rdname listSampleSummaryStatsTables

 #' @description  Returns a character vector of the tables

 #' within the metadata slot of the SingleCellExperiment object.

 #' @param inSCE Input \linkS4class{SingleCellExperiment} object with saved

@@ -195,7 +195,7 @@ setTopHVG <- function(inSCE,

     return(df)

 }

-#' parse `useFeatureSubset` in other functions such as `scaterPCA`, `getUMAP`..

+#' parse `useFeatureSubset` in other functions such as `scaterPCA`, `runUMAP`..

 #' Do checks, and return logical vector. Or character vector as needed by Seurat

 #' methods

 #' @param inSCE Input \linkS4class{SingleCellExperiment} object

@@ -579,8 +579,7 @@ plotBarcodeRankDropsResults <- function(inSCE,

 #' data(scExample, package="singleCellTK")

 #' \dontrun{

 #' sce <- subsetSCECols(sce, colData = "type != 'EmptyDroplet'")

-#' sce <- getUMAP(inSCE=sce, useAssay="counts", logNorm=TRUE, 

-#'                reducedDimName="UMAP")

+#' sce <- runQuickUMAP(sce)

 #' sce <- runScrublet(sce)

 #' plotScrubletResults(inSCE=sce, reducedDimName="UMAP")

 #' }

@@ -878,8 +877,7 @@ plotScrubletResults <- function(inSCE,

 #' @examples

 #' data(scExample, package="singleCellTK")

 #' sce <- subsetSCECols(sce, colData = "type != 'EmptyDroplet'")

-#' sce <- getUMAP(inSCE=sce, useAssay="counts", logNorm=TRUE, 

-#'                reducedDimName="UMAP")

+#' sce <- runQuickUMAP(sce)

 #' sce <- runDoubletFinder(sce)

 #' plotDoubletFinderResults(inSCE=sce, reducedDimName="UMAP")

 #' @export

@@ -1262,8 +1260,7 @@ plotDoubletFinderResults <- function(inSCE,

 #' @examples

 #' data(scExample, package="singleCellTK")

 #' sce <- subsetSCECols(sce, colData = "type != 'EmptyDroplet'")

-#' sce <- getUMAP(inSCE=sce, useAssay="counts", logNorm=TRUE, 

-#'                reducedDimName="UMAP")

+#' sce <- runQuickUMAP(sce)

 #' sce <- runScDblFinder(sce)

 #' plotScDblFinderResults(inSCE=sce, reducedDimName="UMAP")

 #' @export

@@ -1568,8 +1565,7 @@ plotScDblFinderResults <- function(inSCE,

 #' @examples

 #' data(scExample, package="singleCellTK")

 #' sce <- subsetSCECols(sce, colData = "type != 'EmptyDroplet'")

-#' sce <- getUMAP(inSCE=sce, useAssay="counts", logNorm=TRUE, 

-#'                reducedDimName="UMAP")

+#' sce <- runQuickUMAP(sce)

 #' sce <- runCxds(sce)

 #' plotCxdsResults(inSCE=sce, reducedDimName="UMAP")

 #' @export

@@ -1871,8 +1867,7 @@ plotCxdsResults <- function(inSCE,

 #' @examples

 #' data(scExample, package="singleCellTK")

 #' sce <- subsetSCECols(sce, colData = "type != 'EmptyDroplet'")

-#' sce <- getUMAP(inSCE=sce, useAssay="counts", logNorm=TRUE, 

-#'                reducedDimName="UMAP")

+#' sce <- runQuickUMAP(sce)

 #' sce <- runBcds(sce)

 #' plotBcdsResults(inSCE=sce, reducedDimName="UMAP")

 #' @export

@@ -2175,8 +2170,7 @@ plotBcdsResults <- function(inSCE,

 #' @examples

 #' data(scExample, package="singleCellTK")

 #' sce <- subsetSCECols(sce, colData = "type != 'EmptyDroplet'")

-#' sce <- getUMAP(inSCE=sce, useAssay="counts", logNorm=TRUE, 

-#'                reducedDimName="UMAP")

+#' sce <- runQuickUMAP(sce)

 #' sce <- runCxdsBcdsHybrid(sce)

 #' plotScdsHybridResults(inSCE=sce, reducedDimName="UMAP")

 #' @export

@@ -91,7 +91,7 @@ reportCellQC <- function(inSCE, output_file = NULL,

 #' sce <- subsetSCECols(sce, colData = "type != 'EmptyDroplet'")

 #' \dontrun{

 #' sce <- runDecontX(sce)

-#' sce <- getUMAP(sce, useAssay = "counts", logNorm = TRUE)

+#' sce <- runQuickUMAP(sce)

 #' reportQCTool(inSCE = sce, algorithm = "DecontX")

 #' }

 #' @export

@@ -124,7 +124,8 @@ plotBatchCorrCompare <- function(inSCE, corrMat, batch = NULL, condition = NULL,

                                  title = "Batch Variance before correction") +

     ggplot2::theme(text=ggplot2::element_text(size=10))

-  inSCE <- getUMAP(inSCE, useAssay = origAssay, reducedDimName = "umap.before")

+  inSCE <- runUMAP(inSCE, useAssay = origAssay, useReducedDim = NULL, 

+                   reducedDimName = "umap.before")

   umap.before <- plotSCEDimReduceColData(inSCE, batch, "umap.before",

                                          shape = condition, axisLabelSize = 9,

                                          axisSize = 8, dotSize = 1,

@@ -145,10 +146,11 @@ plotBatchCorrCompare <- function(inSCE, corrMat, batch = NULL, condition = NULL,

       ggplot2::theme(text=ggplot2::element_text(size=10))

     if (method == "ComBatSeq") {

-      inSCE <- getUMAP(inSCE, useAssay = corrMat, logNorm = TRUE,

-                       reducedDimName = "umap.after")

+      inSCE <- runUMAP(inSCE, useAssay = corrMat, useReducedDim = NULL, 

+                       logNorm = TRUE, reducedDimName = "umap.after")

     } else {

-      inSCE <- getUMAP(inSCE, useAssay = corrMat, reducedDimName = "umap.after")

+      inSCE <- runUMAP(inSCE, useAssay = corrMat, useReducedDim = NULL,

+                       logNorm = FALSE, reducedDimName = "umap.after")

     }

   } else if (matType == "altExp") {

     # Doing log, because only Seurat returns altExp,

@@ -161,8 +163,8 @@ plotBatchCorrCompare <- function(inSCE, corrMat, batch = NULL, condition = NULL,

                                   title = paste0("Batch Variance corrected with ",

                                                  method)) +

       ggplot2::theme(text=ggplot2::element_text(size=10))

-    inSCE <- getUMAP(inSCE, useAltExp = corrMat, useAssay = corrMat,

-                     reducedDimName = "umap.after")

+    inSCE <- runQuickUMAP(inSCE, useAssay = corrMat, useAltExp = corrMat, 

+                          reducedDimName = "umap.after")

   } else if (matType == "reducedDim") {

     bv.after <- plotBatchVariance(inSCE, useReddim = corrMat, batch = batch,

                                   condition = condition,

@@ -173,7 +175,7 @@ plotBatchCorrCompare <- function(inSCE, corrMat, batch = NULL, condition = NULL,

       SingleCellExperiment::reducedDim(inSCE, "umap.after") <-

         SingleCellExperiment::reducedDim(inSCE, corrMat)

     } else {

-      inSCE <- getUMAP(inSCE, useReducedDim = corrMat,

+      inSCE <- runUMAP(inSCE, useReducedDim = corrMat,

                        reducedDimName = "umap.after")

     }

   } else {

@@ -16,16 +16,16 @@

 #' data("mouseBrainSubsetSCE")

 #' plotTSNE(mouseBrainSubsetSCE, colorBy = "level1class",

 #'          reducedDimName = "TSNE_counts")

-plotTSNE <- function(inSCE, colorBy=NULL, shape=NULL,

-                     reducedDimName="TSNE", runTSNE=FALSE,

-                     useAssay="logcounts"){

+plotTSNE <- function(inSCE, colorBy = NULL, shape = NULL,

+                     reducedDimName = "TSNE", runTSNE = FALSE,

+                     useAssay = "counts"){

   if(!(reducedDimName %in% names(SingleCellExperiment::reducedDims(inSCE)))){

     if (runTSNE){

-      inSCE <- getTSNE(inSCE, useAssay = useAssay,

-                       reducedDimName = reducedDimName)

+      inSCE <- runQuickTSNE(inSCE, useAssay = useAssay,

+                            reducedDimName = reducedDimName)

     } else {

       stop(reducedDimName,

-           " dimension not found. Run getTSNE() or set runTSNE to TRUE.")

+           " dimension not found. Run `runTSNE()` or set `runTSNE` to `TRUE`.")

     }

   }

   tsneDf <- data.frame(SingleCellExperiment::reducedDim(inSCE,

@@ -16,18 +16,18 @@

 #' @examples

 #' data(scExample, package = "singleCellTK")

 #' sce <- subsetSCECols(sce, colData = "type != 'EmptyDroplet'")

-#' sce <- getUMAP(inSCE = sce, useAssay = "counts", reducedDimName = "UMAP")

+#' sce <- runQuickUMAP(sce)

 #' plotUMAP(sce)

 plotUMAP <- function(inSCE, colorBy = NULL, shape = NULL,

                      reducedDimName = "UMAP", runUMAP = FALSE,

-                     useAssay = "logcounts"){

+                     useAssay = "counts"){

   if(!(reducedDimName %in% names(SingleCellExperiment::reducedDims(inSCE)))){

     if (runUMAP){

-      inSCE <- getUMAP(inSCE, useAssay = useAssay,

-                       reducedDimName = reducedDimName)

+      inSCE <- runQuickUMAP(inSCE, useAssay = useAssay,

+                            reducedDimName = reducedDimName)

     } else {

       stop(reducedDimName,

-           " dimension not found. Run getUMAP() or set runUMAP to TRUE.")

+           " dimension not found. Run `runUMAP()` or set `runUMAP` to `TRUE`.")

     }

   }

   UMAPDf <- data.frame(SingleCellExperiment::reducedDim(inSCE,

@@ -1,8 +1,8 @@

 #' Generic Wrapper function for running dimensionality reduction

 #' @details Wrapper function to run one of the available dimensionality

 #' reduction algorithms integrated within SCTK from \code{\link{scaterPCA}},

-#' \code{\link{runSeuratPCA}}, \code{\link{runSeuratICA}}, \code{\link{getTSNE}},

-#' \code{\link{runSeuratTSNE}}, \code{\link{getUMAP}} and

+#' \code{\link{runSeuratPCA}}, \code{\link{runSeuratICA}}, \code{\link{runTSNE}},

+#' \code{\link{runSeuratTSNE}}, \code{\link{runUMAP}} and

 #' \code{\link{runSeuratUMAP}}. Users can use an assay by specifying

 #' \code{useAssay}, use the assay in an altExp by specifying both

 #' \code{useAltExp} and \code{useAssay}, or use a low-dimensionality

@@ -72,12 +72,12 @@ runDimReduce <- function(inSCE,

                        useFeatureSubset = useFeatureSubset, scale = scale,

                        seed = seed, ...)

   } else if (method == "scaterUMAP") {

-    inSCE <- getUMAP(inSCE = inSCE, useAssay = useAssay, useAltExp = useAltExp,

+    inSCE <- runUMAP(inSCE = inSCE, useAssay = useAssay, useAltExp = useAltExp,

                      useReducedDim = useReducedDim,

                      useFeatureSubset = useFeatureSubset, scale = scale,

                      reducedDimName = reducedDimName, seed = seed, ...)

   } else if (method == "rTSNE") {

-    inSCE <- getTSNE(inSCE = inSCE, useAssay = useAssay, useAltExp = useAltExp,

+    inSCE <- runTSNE(inSCE = inSCE, useAssay = useAssay, useAltExp = useAltExp,

                      useReducedDim = useReducedDim,

                      useFeatureSubset = useFeatureSubset, scale = scale,

                      reducedDimName = reducedDimName, seed = seed, ...)

@@ -68,9 +68,12 @@ runFindMarker <- function(inSCE, useAssay = 'logcounts',

                           minMeanExpr = NULL, detectThresh = 0){

   method <- match.arg(method)

   # Input checks will be done in `runDEAnalysis()`

-  if (is.character(cluster) && length(cluster) == 1) clusterName <- cluster

-  else clusterName <- 'findMarker_cluster'

   clusterVar <- .manageCellVar(inSCE, var = cluster)

+  if (is.character(cluster) && length(cluster) == 1) clusterName <- cluster

+  else {

+    clusterName <- 'findMarker_cluster'

+    inSCE[[clusterName]] <- cluster

+  }

   # Iterate

   if(is.factor(clusterVar)){

     # In case inSCE is a subset, when "levels" is a full list of all

@@ -360,9 +360,8 @@ runSoupX <- function(inSCE,

     out <- SoupX::adjustCounts(sc, method = adjustMethod,

                                roundToInt = roundToInt, tol = tol, pCut = pCut)

     message(paste0(date(), " ... Generating UMAP"))

-    # Most of time `useAssay` should be "counts", thus logNorm=TRUE

-    inSCE <- getUMAP(inSCE, useAssay = useAssay, logNorm = TRUE,

-                     reducedDimName = "sampleUMAP")

+    inSCE <- runQuickUMAP(inSCE, useAssay = useAssay, sample = NULL,

+                          reducedDimName = "sampleUMAP")

     return(list(sc = sc, out = out,

                 umap = SingleCellExperiment::reducedDim(inSCE, "sampleUMAP")))

 }

similarity index 77%

rename from R/getTSNE.R

rename to R/runTSNE.R

@@ -1,4 +1,5 @@

 #' Run t-SNE embedding with Rtsne method

+#' @rdname runTSNE

 #' @description T-Stochastic Neighbour Embedding (t-SNE) algorithm is commonly

 #' for 2D visualization of single-cell data. This function wraps the

 #' Rtsne \code{\link[Rtsne]{Rtsne}} function.

@@ -9,18 +10,18 @@

 #' input, so that the result can match with the clustering based on the same

 #' input PCA, and will be much faster.

 #' @param inSCE Input \linkS4class{SingleCellExperiment} object.

+#' @param useReducedDim The low dimension representation to use for UMAP

+#' computation. Default \code{"PCA"}.

 #' @param useAssay Assay to use for tSNE computation. If \code{useAltExp} is

 #' specified, \code{useAssay} has to exist in

-#' \code{assays(altExp(inSCE, useAltExp))}. Default \code{"logcounts"}.

-#' @param useReducedDim The low dimension representation to use for UMAP

-#' computation. Default \code{NULL}.

+#' \code{assays(altExp(inSCE, useAltExp))}. Default \code{NULL}.

 #' @param useAltExp The subset to use for tSNE computation, usually for the

 #' selected.variable features. Default \code{NULL}.

 #' @param reducedDimName a name to store the results of the dimension

 #' reductions. Default \code{"TSNE"}.

 #' @param logNorm Whether the counts will need to be log-normalized prior to

 #' generating the tSNE via \code{\link{scaterlogNormCounts}}. Ignored when using

-#' \code{useReducedDim}. Default \code{FALSE}.

+#' \code{useReducedDim}. Default \code{TRUE}.

 #' @param useFeatureSubset Subset of feature to use for dimension reduction. A

 #' character string indicating a \code{rowData} variable that stores the logical

 #' vector of HVG selection, or a vector that can subset the rows of

@@ -56,23 +57,24 @@

 #' data(scExample, package = "singleCellTK")

 #' sce <- subsetSCECols(sce, colData = "type != 'EmptyDroplet'")

 #' # Run from raw counts

-#' sce <- getTSNE(inSCE = sce, useAssay = "counts", logNorm = TRUE, nTop = 2000,

-#'                scale = TRUE, pca = TRUE)

+#' sce <- runQuickTSNE(sce)

 #' \dontrun{

 #' # Run from PCA

 #' sce <- scaterlogNormCounts(sce, "logcounts")

 #' sce <- runModelGeneVar(sce)

+#' sce <- setTopHVG(sce, method = "modelGeneVar", hvgNumber = 2000, 

+#'                  featureSubsetName = "HVG_modelGeneVar2000")

 #' sce <- scaterPCA(sce, useAssay = "logcounts",

 #'                  useFeatureSubset = "HVG_modelGeneVar2000", scale = TRUE)

-#' sce <- getTSNE(sce, useReducedDim = "PCA")

+#' sce <- runTSNE(sce, useReducedDim = "PCA")

 #' }

 #' @importFrom S4Vectors metadata<-

-getTSNE <- function(inSCE, useAssay = "logcounts", useReducedDim = NULL,

-                    useAltExp = NULL, reducedDimName = "TSNE", logNorm = FALSE,

+runTSNE <- function(inSCE, useReducedDim = "PCA", useAssay = NULL, 

+                    useAltExp = NULL, reducedDimName = "TSNE", logNorm = TRUE,

                     useFeatureSubset = NULL, nTop = 2000, center = TRUE,

                     scale = TRUE, pca = TRUE, partialPCA = FALSE,

                     initialDims = 25, theta = 0.5, perplexity = 30,

-                    nIterations = 1000, numThreads = 1, seed = NULL){

+                    nIterations = 1000, numThreads = 1, seed = NULL) {

   params <- as.list(environment())

   params$inSCE <- NULL

   # Note: useMat = list(useAssay = useAssay, ...)

@@ -84,13 +86,13 @@ getTSNE <- function(inSCE, useAssay = "logcounts", useReducedDim = NULL,

                              returnMatrix = FALSE)$names

   params$useAssay <- useMat$useAssay

   useAssay <- useMat$useAssay

-

+  

   if (!is.null(useAltExp)) {

     sce <- SingleCellExperiment::altExp(inSCE, useAltExp)

   } else {

     sce <- inSCE

   }

-

+  

   if (!is.null(useAssay)) {

     if (isTRUE(logNorm)) {

       sce <- scaterlogNormCounts(sce, assayName = "logcounts", useAssay = useAssay)

@@ -125,7 +127,7 @@ getTSNE <- function(inSCE, useAssay = "logcounts", useReducedDim = NULL,

       mat <- mat[,seq(initialDims)]

     }

   }

-

+  

   if (is.null(perplexity)){

     perplexity <- floor(ncol(inSCE) / 5)

   }

@@ -147,3 +149,36 @@ getTSNE <- function(inSCE, useAssay = "logcounts", useReducedDim = NULL,

   metadata(inSCE)$sctk$runDimReduce$embedding[[reducedDimName]] <- params

   return(inSCE)

 }

+

+#' @rdname runTSNE

+#' @param ... Other parameters to be passed to \code{runTSNE}

+#' @export

+runQuickTSNE <- function(inSCE, useAssay = "counts", ...) {

+  args <- list(...)

+  if (!is.null(args$useReducedDim)) {

+    warning("Forcing `useReducedDim` to be `NULL`. Please use `runTSNE` for ",

+            "using reducedDim.")

+  }

+  args$useReducedDim <- NULL

+  args <- c(list(inSCE = inSCE, useAssay = useAssay, useReducedDim = NULL), 

+            args)

+  inSCE <- do.call("runTSNE", args = args)

+  return(inSCE)

+}

+

+#' @rdname runTSNE

+#' @export

+getTSNE <- function(inSCE, useReducedDim = "PCA", useAssay = NULL, 

+                    useAltExp = NULL, reducedDimName = "TSNE", logNorm = TRUE,

+                    useFeatureSubset = NULL, nTop = 2000, center = TRUE,

+                    scale = TRUE, pca = TRUE, partialPCA = FALSE,

+                    initialDims = 25, theta = 0.5, perplexity = 30,

+                    nIterations = 1000, numThreads = 1, seed = NULL) {

+  .Deprecated("runTSNE")

+  runTSNE(inSCE = inSCE, useReducedDim = useReducedDim, useAssay = useAssay, 

+          useAltExp = useAltExp, reducedDimName = reducedDimName, 

+          logNorm = logNorm, useFeatureSubset = useFeatureSubset, nTop = nTop, 

+          center = center, scale = scale, pca = pca, partialPCA = partialPCA,

+          initialDims = initialDims, theta = theta, perplexity = perplexity,

+          nIterations = nIterations, numThreads = numThreads, seed = seed)

+}

similarity index 71%

rename from R/getUMAP.R

rename to R/runUMAP.R

@@ -1,21 +1,26 @@

 #' Run UMAP embedding with scater method

+#' @rdname runUMAP

 #' @description Uniform Manifold Approximation and Projection (UMAP) algorithm

-#' is commonly for 2D visualization of single-cell data. This function wraps the

-#' scater \code{\link[scater]{calculateUMAP}} function.

-#'

-#' With this funciton, users can create UMAP embedding directly from raw count

-#' matrix, with necessary preprocessing including normalization, scaling,

-#' dimension reduction all automated. Yet we still recommend having the PCA as

-#' input, so that the result can match with the clustering based on the same

-#' input PCA.

+#' is commonly for 2D visualization of single-cell data. These functions wrap 

+#' the scater \code{\link[scater]{calculateUMAP}} function.

+#' 

+#' Users can use \code{runQuickUMAP} to directly create UMAP embedding from raw

+#' count matrix, with necessary preprocessing including normalization, variable

+#' feature selection, scaling, dimension reduction all automated. Therefore, 

+#' \code{useReducedDim} is disabled for \code{runQuickUMAP}. 

+#' 

+#' In a complete analysis, we still recommend having dimension reduction such as

+#' PCA created beforehand and select proper numbers of dimensions for using

+#' \code{runUMAP}, so that the result can match with the clustering based on the

+#' same input PCA. 

 #' @param inSCE Input \linkS4class{SingleCellExperiment} object.

+#' @param useReducedDim The low dimension representation to use for UMAP

+#' computation. If \code{useAltExp} is specified, \code{useReducedDim} has to

+#' exist in \code{reducedDims(altExp(inSCE, useAltExp))}. Default \code{"PCA"}.

 #' @param useAssay Assay to use for UMAP computation. If \code{useAltExp} is

 #' specified, \code{useAssay} has to exist in

 #' \code{assays(altExp(inSCE, useAltExp))}. Ignored when using

-#' \code{useReducedDim}. Default \code{"logcounts"}.

-#' @param useReducedDim The low dimension representation to use for UMAP

-#' computation. If \code{useAltExp} is specified, \code{useReducedDim} has to

-#' exist in \code{reducedDims(altExp(inSCE, useAltExp))}. Default \code{NULL}.

+#' \code{useReducedDim}. Default \code{NULL}.

 #' @param useAltExp The subset to use for UMAP computation, usually for the

 #' selected variable features. Default \code{NULL}.

 #' @param sample Character vector. Indicates which sample each cell belongs to.

@@ -25,7 +30,7 @@

 #' coordinates obtained from this method. Default \code{"UMAP"}.

 #' @param logNorm Whether the counts will need to be log-normalized prior to

 #' generating the UMAP via \code{\link{scaterlogNormCounts}}. Ignored when using

-#' \code{useReducedDim}. Default \code{FALSE}.

+#' \code{useReducedDim}. Default \code{TRUE}.

 #' @param useFeatureSubset Subset of feature to use for dimension reduction. A

 #' character string indicating a \code{rowData} variable that stores the logical

 #' vector of HVG selection, or a vector that can subset the rows of

@@ -67,23 +72,23 @@

 #' data(scExample, package = "singleCellTK")

 #' sce <- subsetSCECols(sce, colData = "type != 'EmptyDroplet'")

 #' # Run from raw counts

-#' sce <- getUMAP(inSCE = sce, useAssay = "counts", logNorm = TRUE, nTop = 2000,

-#'                scale = TRUE, pca = TRUE)

+#' sce <- runQuickUMAP(sce)

 #' \dontrun{

 #' # Run from PCA

 #' sce <- scaterlogNormCounts(sce, "logcounts")

 #' sce <- runModelGeneVar(sce)

 #' sce <- scaterPCA(sce, useAssay = "logcounts",

 #'                  useFeatureSubset = "HVG_modelGeneVar2000", scale = TRUE)

-#' sce <- getUMAP(sce, useReducedDim = "PCA")

+#' sce <- runUMAP(sce, useReducedDim = "PCA")

 #' }

 #' @importFrom S4Vectors metadata<-

-getUMAP <- function(inSCE, useAssay = "logcounts", useReducedDim = NULL,

+#' @importFrom BiocParallel SerialParam

+runUMAP <- function(inSCE, useReducedDim = "PCA", useAssay = NULL, 

                     useAltExp = NULL, sample = NULL, reducedDimName = "UMAP",

-                    logNorm = FALSE, useFeatureSubset = NULL, nTop = 2000,

+                    logNorm = TRUE, useFeatureSubset = NULL, nTop = 2000,

                     scale = TRUE, pca = TRUE, initialDims = 25, nNeighbors = 30,

                     nIterations = 200, alpha = 1, minDist = 0.01, spread = 1,

-                    seed = NULL, BPPARAM = BiocParallel::SerialParam()) {

+                    seed = NULL, BPPARAM = SerialParam()) {

   params <- as.list(environment())

   params$inSCE <- NULL

   params$BPPARAM <- NULL

@@ -120,7 +125,7 @@ getUMAP <- function(inSCE, useAssay = "logcounts", useReducedDim = NULL,

     if (!isTRUE(pca) & !is.null(useAssay)) {

       initialDims <- NULL

     }

-

+    

     nNeighbors <- min(ncol(sceSample), nNeighbors)

     message(paste0(date(), " ... Computing Scater UMAP for sample '",

                    samples[i], "'."))

@@ -145,3 +150,39 @@ getUMAP <- function(inSCE, useAssay = "logcounts", useReducedDim = NULL,

   metadata(inSCE)$sctk$runDimReduce$embedding[[reducedDimName]] <- params

   return(inSCE)

 }

+

+#' @rdname runUMAP

+#' @param ... Parameters passed to \code{runUMAP}

+#' @importFrom BiocParallel SerialParam

+#' @export

+runQuickUMAP <- function(inSCE, useAssay = "counts", sample = "sample", ...) {

+  args <- list(...)

+  if (!is.null(args$useReducedDim)) {

+    warning("Forcing `useReducedDim` to be `NULL`. Please use `runUMAP` for ",

+            "using reducedDim.")

+  }

+  args$useReducedDim <- NULL

+  args <- c(list(inSCE = inSCE, useAssay = useAssay, useReducedDim = NULL), 

+            args)

+  inSCE <- do.call("runUMAP", args = args)

+  return(inSCE)

+}

+

+#' @rdname runUMAP

+#' @export

+#' @importFrom BiocParallel SerialParam

+getUMAP <- function(inSCE, useReducedDim = "PCA", useAssay = NULL, 

+                    useAltExp = NULL, sample = NULL, reducedDimName = "UMAP",

+                    logNorm = TRUE, useFeatureSubset = NULL, nTop = 2000,

+                    scale = TRUE, pca = TRUE, initialDims = 25, nNeighbors = 30,

+                    nIterations = 200, alpha = 1, minDist = 0.01, spread = 1,

+                    seed = NULL, BPPARAM = SerialParam()) {

+  .Deprecated("runUMAP")

+  runUMAP(inSCE, useReducedDim = useReducedDim, useAssay = useAssay, 

+          useAltExp = useAltExp, sample = sample, 

+          reducedDimName = reducedDimName,

+          logNorm = logNorm, useFeatureSubset = useFeatureSubset, nTop = nTop,

+          scale = scale, pca = pca, initialDims = initialDims, 

+          nNeighbors = nNeighbors, nIterations = nIterations, alpha = alpha, 

+          minDist = minDist, spread = spread, seed = seed, BPPARAM = BPPARAM)

+}

@@ -1,4 +1,5 @@

 #' @rdname getSampleSummaryStatsTable

+#' @importFrom S4Vectors metadata

 setMethod("getSampleSummaryStatsTable", "SingleCellExperiment", function(inSCE, statsName, ...){

     allStatsNames <- listSampleSummaryStatsTables(inSCE)

     if(!statsName %in% allStatsNames){

@@ -6,28 +7,30 @@ setMethod("getSampleSummaryStatsTable", "SingleCellExperiment", function(inSCE,

                    "The following are the names of the tables stored:",

                    paste(allStatsNames, collapse = ",")))

     }else{

-        return(inSCE@metadata$sctk$sample_summary[[statsName]])

+        return(metadata(inSCE)$sctk$sample_summary[[statsName]])

     }

 })

-#' @rdname setSampleSummaryStatsTable<-

+#' @rdname getSampleSummaryStatsTable

+#' @importFrom S4Vectors metadata

 setReplaceMethod("setSampleSummaryStatsTable", c("SingleCellExperiment", "ANY"), function(inSCE, statsName, ..., value) {

-    inSCE@metadata$sctk$sample_summary[[statsName]] <- value

+    metadata(inSCE)$sctk$sample_summary[[statsName]] <- value

     return(inSCE)

 })

 #' @rdname listSampleSummaryStatsTables

+#' @importFrom S4Vectors metadata

 setMethod("listSampleSummaryStatsTables", "SingleCellExperiment", function(inSCE, ...){

-    if(is.null(inSCE@metadata$sctk$sample_summary)){

+    if(is.null(metadata(inSCE)$sctk$sample_summary)){

         stop(paste("No sample-level QC tables are available.",

                      "Please try executing functions such as sampleSummaryStats first."))

     }else{

-        allStatsNames <- names(inSCE@metadata$sctk$sample_summary)

+        allStatsNames <- names(metadata(inSCE)$sctk$sample_summary)

         if(is.null(allStatsNames) || length(allStatsNames) == 0){

             stop(paste("No sample-level QC tables are available.",

                          "Please try executing functions such as sampleSummaryStats first."))

         }else{

-            return(names(inSCE@metadata$sctk$sample_summary))

+            return(names(metadata(inSCE)$sctk$sample_summary))

         }

     }

 })

@@ -38,15 +38,17 @@ runCxds <- function(inSCE,

     estNdbl = FALSE,

     useAssay = "counts") {

-    if (!is.null(sample)) {

-        if (length(sample) != ncol(inSCE)) {

-            stop("'sample' must be the same length as the number",

-                " of columns in 'inSCE'")

-        }

-    } else {

-        sample <- rep(1, ncol(inSCE))

-    }

-

+    #if (!is.null(sample)) {

+    #    if (length(sample) != ncol(inSCE)) {

+    #        stop("'sample' must be the same length as the number",

+    #            " of columns in 'inSCE'")

+    #    }

+    #} else {

+    #    sample <- rep(1, ncol(inSCE))

+    #}

+    if (!is.null(sample)) sample <- .manageCellVar(inSCE, var = sample)

+    else sample <- rep(1, ncol(inSCE))

+    

     message(paste0(date(), " ... Running 'cxds'"))

     ## Getting current arguments

@@ -160,14 +162,16 @@ runBcds <- function(inSCE,

     useAssay = "counts"

     ) {

-    if (!is.null(sample)) {

-        if (length(sample) != ncol(inSCE)) {

-            stop("'sample' must be the same length as the number",

-                " of columns in 'inSCE'")

-        }

-    } else {

-        sample <- rep(1, ncol(inSCE))

-    }

+    #if (!is.null(sample)) {

+    #    if (length(sample) != ncol(inSCE)) {

+    #        stop("'sample' must be the same length as the number",

+    #            " of columns in 'inSCE'")

+    #    }

+    #} else {

+    #    sample <- rep(1, ncol(inSCE))

+    #}

+    if (!is.null(sample)) sample <- .manageCellVar(inSCE, var = sample)

+    else sample <- rep(1, ncol(inSCE))

     message(paste0(date(), " ... Running 'bcds'"))

@@ -287,14 +291,16 @@ runCxdsBcdsHybrid <- function(inSCE,

     force = FALSE,

     useAssay = "counts") {

-    if (!is.null(sample)) {

-        if (length(sample) != ncol(inSCE)) {

-            stop("'sample' must be the same length as the number",

-                " of columns in 'inSCE'")

-        }

-    } else {

-        sample <- rep(1, ncol(inSCE))

-    }

+    #if (!is.null(sample)) {

+    #    if (length(sample) != ncol(inSCE)) {

+    #        stop("'sample' must be the same length as the number",

+    #            " of columns in 'inSCE'")

+    #    }

+    #} else {

+    #    sample <- rep(1, ncol(inSCE))

+    #}

+    if (!is.null(sample)) sample <- .manageCellVar(inSCE, var = sample)

+    else sample <- rep(1, ncol(inSCE))

     message(paste0(date(), " ... Running 'cxds_bcds_hybrid'"))

@@ -104,18 +104,16 @@ if (typeof(S4Vectors::metadata(sce.qc)$assayType) == 'list') {

   S4Vectors::metadata(sce.qc)$assayType <- assayType

 }

-sce.qc <- getUMAP(sce.qc, useAssay = "counts", reducedDimName = "QC_UMAP", sample = sceSample)

+sce.qc <- runQuickUMAP(sce.qc, reducedDimName = "QC_UMAP", sample = sceSample)

 if (is.null(reducedDimName)) {

   allSampleReducedDim <- "All_UMAP"

-  sce.qc <- getUMAP(sce.qc, useAssay = "counts", 

-                    reducedDimName = allSampleReducedDim, sample = NULL)

+  sce.qc <- runQuickUMAP(sce.qc, reducedDimName = allSampleReducedDim, sample = NULL)

 } else if (!reducedDimName %in% reducedDimNames(sce.qc)) {

   warning("'reducedDimName' not found in the reducedDimNames of the sce object. ",

   "Generate new reduced dimension reduction for all samples. ")

   allSampleReducedDim <- "All_UMAP"

-  sce.qc <- getUMAP(sce.qc, useAssay = "counts", 

-                    reducedDimName = allSampleReducedDim, sample = NULL)

+  sce.qc <- runQuickUMAP(sce.qc, reducedDimName = allSampleReducedDim, sample = NULL)

 } else {

   allSampleReducedDim <- reducedDimName

 }

@@ -592,3 +592,39 @@ dataAnnotationColor <- function(inSCE, axis = NULL,

     }

     return(allColorMap)

 }

+

+# Pass newly generated QC metric variable from vals$original to vals$counts, the

+# latter might be a subset.

+passQCVar <- function(sce.original, sce.counts, algoList) {

+  vars <- c()

+  for (a in algoList) {

+    if (a == "scDblFinder") {

+      new <- grep("scDblFinder", names(colData(sce.original)), value = TRUE)

+    } else if (a == "cxds") {

+      new <- grep("scds_cxds", names(colData(sce.original)), value = TRUE)

+    } else if (a == "bcds") {

+      new <- grep("scds_bcds", names(colData(sce.original)), value = TRUE)

+    } else if (a == "cxds_bcds_hybrid") {

+      new <- grep("scds_hybrid", names(colData(sce.original)), value = TRUE)

+    } else if (a == "decontX") {

+      new <- grep("decontX", names(colData(sce.original)), value = TRUE)

+    } else if (a == "soupX") {

+      new <- grep("soupX", names(colData(sce.original)), value = TRUE)

+    } else if (a == "scrublet") {

+      new <- grep("scrublet", names(colData(sce.original)), value = TRUE)

+    } else if (a == "doubletFinder") {

+      new <- grep("doubletFinder", names(colData(sce.original)), value = TRUE)

+    } else if (a == "QCMetrics") {

+      new <- c("total", "sum", "detected")

+      new <- c(new, grep("percent.top", names(colData(sce.original)), value = TRUE))

+      new <- c(new, grep("mito_", names(colData(sce.original)), value = TRUE))

+      new <- c(new, grep("^subsets_.+_sum$", names(colData(sce.original)), value = TRUE))

+      new <- c(new, grep("^subsets_.+_detected$", names(colData(sce.original)), value = TRUE))

+      new <- c(new, grep("^subsets_.+_percent$", names(colData(sce.original)), value = TRUE))

+    } 

+    vars <- c(vars, new)

+  }

+  sce.original <- sce.original[rownames(sce.counts), colnames(sce.counts)]

+  colData(sce.counts)[vars] <- colData(sce.original)[vars]

+  return(sce.counts)

+}

@@ -227,10 +227,12 @@ shinyServer(function(input, output, session) {

   }

-  updateSelectInputTag <- function(session, inputId, choices = NULL, selected = NULL,

-                                   label = "Select assay:", tags = NULL, recommended = NULL, showTags = TRUE,

-                                   redDims = FALSE){

-    choices <- expTaggedData(vals$counts, tags, redDims = redDims, showTags = showTags, recommended = recommended)

+  updateSelectInputTag <- function(session, inputId, choices = NULL, 

+                                   selected = NULL, label = "Select assay:", 

+                                   tags = NULL, recommended = NULL, 

+                                   showTags = TRUE, redDims = FALSE, 

+                                   inSCE = vals$counts){

+    choices <- expTaggedData(inSCE, tags, redDims = redDims, showTags = showTags, recommended = recommended)

     updateSelectizeInput(session = session, inputId = inputId, label = label, choices = choices, selected = selected)

   }

@@ -294,7 +296,7 @@ shinyServer(function(input, output, session) {

                            recommended = c("transformed", "normalized"))

     }

     updateSelectInputTag(session, "filterAssaySelect", choices = currassays)

-    updateSelectInputTag(session, "qcAssaySelect", recommended = "raw")

+    updateSelectInputTag(session, "qcAssaySelect", recommended = "raw", inSCE = vals$original)

     updateSelectInputTag(session, "celdaAssay", choices = currassays)

     updateSelectInputTag(session, "celdaAssayGS", choices = currassays)

     updateSelectInputTag(session, "celdaAssaytSNE", choices = currassays)

@@ -1735,12 +1737,12 @@ shinyServer(function(input, output, session) {

   updateQCPlots <- function() {

     # get selected sample from run QC section

-    if (!is.null(vals$counts)) {

+    if (!is.null(vals$original)) {

       qcSample <- input$qcSampleSelect

       if (qcSample == "None") {

         qcSample <- NULL

       } else {

-        qcSample <- colData(vals$counts)[,input$qcSampleSelect]

+        qcSample <- colData(vals$original)[,input$qcSampleSelect]

       }

       # build list of selected algos

       algoList = list()

@@ -1749,16 +1751,16 @@ shinyServer(function(input, output, session) {

           algoList <- c(algoList, algo)

         }

       }

-      # only run getUMAP if there are no reducedDimNames

+      # only run runUMAP if there are no reducedDimNames

       # redDimName <- input$qcPlotRedDim

       # show the tabs for the result plots  output[[qc_plot_ids[[a]]]]

       showQCResTabs(vals, algoList, qc_algo_status, qc_plot_ids)

-      arrangeQCPlots(vals$counts, input, output, algoList,

-                     colData(vals$counts)[[input$qcSampleSelect]], qc_plot_ids,

+      arrangeQCPlots(vals$original, input, output, algoList,

+                     colData(vals$original)[[input$qcSampleSelect]], qc_plot_ids,

                      qc_algo_status, input$QCUMAPName)

-      uniqueSampleNames = unique(colData(vals$counts)[[input$qcSampleSelect]])

+      uniqueSampleNames = unique(colData(vals$original)[[input$qcSampleSelect]])

       for (algo in algoList) {

         qc_algo_status[[algo]] <- list(self="done")

         if (length(uniqueSampleNames) > 1) {

@@ -1778,7 +1780,7 @@ shinyServer(function(input, output, session) {

           selector = "#qcPageErrors",

           ui = wellPanel(id = "noSelected", tags$b("Please select at least one algorithm.", style = "color: red;"))

         )

-      } else if (is.null(vals$counts)) {

+      } else if (is.null(vals$original)) {

         insertUI(

           selector = "#qcPageErrors",

           ui = wellPanel(id = "noSCE", tags$b("Please upload a sample first.", style = "color: red;"))

@@ -1868,7 +1870,7 @@ shinyServer(function(input, output, session) {

           }

         }

         # run selected cell QC algorithms

-        vals$counts <- runCellQC(inSCE = vals$counts,

+        vals$original <- runCellQC(inSCE = vals$original,

                                  algorithms = algoList,

                                  sample = qcSample,

                                  collectionName = qcCollName,

@@ -1877,27 +1879,31 @@ shinyServer(function(input, output, session) {

                                  mitoGeneLocation = mgsLoc,

                                  useAssay = input$qcAssaySelect,

                                  paramsList = paramsList)

+        # Only copy the newly generated colData variables to vals$counts, but

+        # not replacing the vals$counts. vals$counts might have already become

+        # a subset.

+        vals$counts <- passQCVar(vals$original, vals$counts, algoList)

         updateColDataNames()

         updateAssayInputs()

-        # redDimList <- strsplit(reducedDimNames(vals$counts), " ")

-        # run getUMAP if doublet/ambient RNA detection conducted

+        # redDimList <- strsplit(reducedDimNames(vals$original), " ")

+        # run runUMAP if doublet/ambient RNA detection conducted

         #umap generated during soupX, skip for now

-        if(length(intersect(c("scDblFinder", "cxds", "bcds",

+        if (length(intersect(c("scDblFinder", "cxds", "bcds",

              "cxds_bcds_hybrid", "decontX", #"soupX",

-             "scrublet", "doubletFinder"), algoList))){

+             "scrublet", "doubletFinder"), algoList)) > 0) {

           message(paste0(date(), " ... Running 'UMAP'"))

-          vals$counts <- getUMAP(inSCE = vals$counts,

-                                 sample = qcSample,

-                                 useAssay = input$qcAssaySelect,

-                                 nNeighbors = input$UnNeighbors,

-                                 nIterations = input$UnIterations,

-                                 alpha = input$Ualpha,

-                                 minDist = input$UminDist,

-                                 spread = input$Uspread,

-                                 initialDims = input$UinitialDims,

-                                 reducedDimName = input$QCUMAPName,

-                                 seed = input$Useed

-                                 )

+          vals$original <- runUMAP(inSCE = vals$original,

+                                   sample = qcSample,

+                                   useAssay = input$qcAssaySelect,

+                                   useReducedDim = NULL,

+                                   nNeighbors = input$UnNeighbors,

+                                   nIterations = input$UnIterations,

+                                   alpha = input$Ualpha,

+                                   minDist = input$UminDist,

+                                   spread = input$Uspread,

+                                   initialDims = input$UinitialDims,

+                                   reducedDimName = input$QCUMAPName,

+                                   seed = input$Useed)

         }

         message(paste0(date(), " ... QC Complete"))

@@ -1920,15 +1926,15 @@ shinyServer(function(input, output, session) {

   rowFilteringParams <- reactiveValues(params = list(), id_count = 0)

   observeEvent(input$addFilteringParam, {

-    if (!is.null(vals$counts)) {

-      showModal(filteringModal(colNames = names(colData(vals$counts))))