Browse code

Deprecate "getUMAP", add "runUMAP" and "runQuickUMAP"

Yichen Wang authored on 28/09/2022 03:49:28
Showing 21 changed files

... ...
@@ -177,6 +177,7 @@ export(runMNNCorrect)
177 177
 export(runModelGeneVar)
178 178
 export(runNormalization)
179 179
 export(runPerCellQC)
180
+export(runQuickUMAP)
180 181
 export(runSCANORAMA)
181 182
 export(runSCMerge)
182 183
 export(runScDblFinder)
... ...
@@ -200,6 +201,7 @@ export(runSoupX)
200 201
 export(runTSCAN)
201 202
 export(runTSCANClusterDEAnalysis)
202 203
 export(runTSCANDEG)
204
+export(runUMAP)
203 205
 export(runVAM)
204 206
 export(runWilcox)
205 207
 export(runZINBWaVE)
... ...
@@ -242,6 +244,7 @@ import(DropletUtils)
242 244
 import(GSVAdata)
243 245
 import(SingleCellExperiment)
244 246
 import(fishpond)
247
+importFrom(BiocParallel,SerialParam)
245 248
 importFrom(S4Vectors,"metadata<-")
246 249
 importFrom(S4Vectors,metadata)
247 250
 importFrom(SingleCellExperiment,"counts<-")
... ...
@@ -195,7 +195,7 @@ setTopHVG <- function(inSCE,
195 195
     return(df)
196 196
 }
197 197
 
198
-#' parse `useFeatureSubset` in other functions such as `scaterPCA`, `getUMAP`..
198
+#' parse `useFeatureSubset` in other functions such as `scaterPCA`, `runUMAP`..
199 199
 #' Do checks, and return logical vector. Or character vector as needed by Seurat
200 200
 #' methods
201 201
 #' @param inSCE Input \linkS4class{SingleCellExperiment} object
... ...
@@ -579,8 +579,7 @@ plotBarcodeRankDropsResults <- function(inSCE,
579 579
 #' data(scExample, package="singleCellTK")
580 580
 #' \dontrun{
581 581
 #' sce <- subsetSCECols(sce, colData = "type != 'EmptyDroplet'")
582
-#' sce <- getUMAP(inSCE=sce, useAssay="counts", logNorm=TRUE, 
583
-#'                reducedDimName="UMAP")
582
+#' sce <- runQuickUMAP(sce)
584 583
 #' sce <- runScrublet(sce)
585 584
 #' plotScrubletResults(inSCE=sce, reducedDimName="UMAP")
586 585
 #' }
... ...
@@ -878,8 +877,7 @@ plotScrubletResults <- function(inSCE,
878 877
 #' @examples
879 878
 #' data(scExample, package="singleCellTK")
880 879
 #' sce <- subsetSCECols(sce, colData = "type != 'EmptyDroplet'")
881
-#' sce <- getUMAP(inSCE=sce, useAssay="counts", logNorm=TRUE, 
882
-#'                reducedDimName="UMAP")
880
+#' sce <- runQuickUMAP(sce)
883 881
 #' sce <- runDoubletFinder(sce)
884 882
 #' plotDoubletFinderResults(inSCE=sce, reducedDimName="UMAP")
885 883
 #' @export
... ...
@@ -1262,8 +1260,7 @@ plotDoubletFinderResults <- function(inSCE,
1262 1260
 #' @examples
1263 1261
 #' data(scExample, package="singleCellTK")
1264 1262
 #' sce <- subsetSCECols(sce, colData = "type != 'EmptyDroplet'")
1265
-#' sce <- getUMAP(inSCE=sce, useAssay="counts", logNorm=TRUE, 
1266
-#'                reducedDimName="UMAP")
1263
+#' sce <- runQuickUMAP(sce)
1267 1264
 #' sce <- runScDblFinder(sce)
1268 1265
 #' plotScDblFinderResults(inSCE=sce, reducedDimName="UMAP")
1269 1266
 #' @export
... ...
@@ -1568,8 +1565,7 @@ plotScDblFinderResults <- function(inSCE,
1568 1565
 #' @examples
1569 1566
 #' data(scExample, package="singleCellTK")
1570 1567
 #' sce <- subsetSCECols(sce, colData = "type != 'EmptyDroplet'")
1571
-#' sce <- getUMAP(inSCE=sce, useAssay="counts", logNorm=TRUE, 
1572
-#'                reducedDimName="UMAP")
1568
+#' sce <- runQuickUMAP(sce)
1573 1569
 #' sce <- runCxds(sce)
1574 1570
 #' plotCxdsResults(inSCE=sce, reducedDimName="UMAP")
1575 1571
 #' @export
... ...
@@ -1871,8 +1867,7 @@ plotCxdsResults <- function(inSCE,
1871 1867
 #' @examples
1872 1868
 #' data(scExample, package="singleCellTK")
1873 1869
 #' sce <- subsetSCECols(sce, colData = "type != 'EmptyDroplet'")
1874
-#' sce <- getUMAP(inSCE=sce, useAssay="counts", logNorm=TRUE, 
1875
-#'                reducedDimName="UMAP")
1870
+#' sce <- runQuickUMAP(sce)
1876 1871
 #' sce <- runBcds(sce)
1877 1872
 #' plotBcdsResults(inSCE=sce, reducedDimName="UMAP")
1878 1873
 #' @export
... ...
@@ -2175,8 +2170,7 @@ plotBcdsResults <- function(inSCE,
2175 2170
 #' @examples
2176 2171
 #' data(scExample, package="singleCellTK")
2177 2172
 #' sce <- subsetSCECols(sce, colData = "type != 'EmptyDroplet'")
2178
-#' sce <- getUMAP(inSCE=sce, useAssay="counts", logNorm=TRUE, 
2179
-#'                reducedDimName="UMAP")
2173
+#' sce <- runQuickUMAP(sce)
2180 2174
 #' sce <- runCxdsBcdsHybrid(sce)
2181 2175
 #' plotScdsHybridResults(inSCE=sce, reducedDimName="UMAP")
2182 2176
 #' @export
... ...
@@ -91,7 +91,7 @@ reportCellQC <- function(inSCE, output_file = NULL,
91 91
 #' sce <- subsetSCECols(sce, colData = "type != 'EmptyDroplet'")
92 92
 #' \dontrun{
93 93
 #' sce <- runDecontX(sce)
94
-#' sce <- getUMAP(sce, useAssay = "counts", logNorm = TRUE)
94
+#' sce <- runQuickUMAP(sce)
95 95
 #' reportQCTool(inSCE = sce, algorithm = "DecontX")
96 96
 #' }
97 97
 #' @export
... ...
@@ -124,7 +124,8 @@ plotBatchCorrCompare <- function(inSCE, corrMat, batch = NULL, condition = NULL,
124 124
                                  title = "Batch Variance before correction") +
125 125
     ggplot2::theme(text=ggplot2::element_text(size=10))
126 126
 
127
-  inSCE <- getUMAP(inSCE, useAssay = origAssay, reducedDimName = "umap.before")
127
+  inSCE <- runUMAP(inSCE, useAssay = origAssay, useReducedDim = NULL, 
128
+                   reducedDimName = "umap.before")
128 129
   umap.before <- plotSCEDimReduceColData(inSCE, batch, "umap.before",
129 130
                                          shape = condition, axisLabelSize = 9,
130 131
                                          axisSize = 8, dotSize = 1,
... ...
@@ -145,10 +146,11 @@ plotBatchCorrCompare <- function(inSCE, corrMat, batch = NULL, condition = NULL,
145 146
       ggplot2::theme(text=ggplot2::element_text(size=10))
146 147
 
147 148
     if (method == "ComBatSeq") {
148
-      inSCE <- getUMAP(inSCE, useAssay = corrMat, logNorm = TRUE,
149
-                       reducedDimName = "umap.after")
149
+      inSCE <- runUMAP(inSCE, useAssay = corrMat, useReducedDim = NULL, 
150
+                       logNorm = TRUE, reducedDimName = "umap.after")
150 151
     } else {
151
-      inSCE <- getUMAP(inSCE, useAssay = corrMat, reducedDimName = "umap.after")
152
+      inSCE <- runUMAP(inSCE, useAssay = corrMat, useReducedDim = NULL,
153
+                       logNorm = FALSE, reducedDimName = "umap.after")
152 154
     }
153 155
   } else if (matType == "altExp") {
154 156
     # Doing log, because only Seurat returns altExp,
... ...
@@ -161,8 +163,8 @@ plotBatchCorrCompare <- function(inSCE, corrMat, batch = NULL, condition = NULL,
161 163
                                   title = paste0("Batch Variance corrected with ",
162 164
                                                  method)) +
163 165
       ggplot2::theme(text=ggplot2::element_text(size=10))
164
-    inSCE <- getUMAP(inSCE, useAltExp = corrMat, useAssay = corrMat,
165
-                     reducedDimName = "umap.after")
166
+    inSCE <- runQuickUMAP(inSCE, useAssay = corrMat, useAltExp = corrMat, 
167
+                          reducedDimName = "umap.after")
166 168
   } else if (matType == "reducedDim") {
167 169
     bv.after <- plotBatchVariance(inSCE, useReddim = corrMat, batch = batch,
168 170
                                   condition = condition,
... ...
@@ -173,7 +175,7 @@ plotBatchCorrCompare <- function(inSCE, corrMat, batch = NULL, condition = NULL,
173 175
       SingleCellExperiment::reducedDim(inSCE, "umap.after") <-
174 176
         SingleCellExperiment::reducedDim(inSCE, corrMat)
175 177
     } else {
176
-      inSCE <- getUMAP(inSCE, useReducedDim = corrMat,
178
+      inSCE <- runUMAP(inSCE, useReducedDim = corrMat,
177 179
                        reducedDimName = "umap.after")
178 180
     }
179 181
   } else {
... ...
@@ -16,18 +16,18 @@
16 16
 #' @examples
17 17
 #' data(scExample, package = "singleCellTK")
18 18
 #' sce <- subsetSCECols(sce, colData = "type != 'EmptyDroplet'")
19
-#' sce <- getUMAP(inSCE = sce, useAssay = "counts", reducedDimName = "UMAP")
19
+#' sce <- runQuickUMAP(sce)
20 20
 #' plotUMAP(sce)
21 21
 plotUMAP <- function(inSCE, colorBy = NULL, shape = NULL,
22 22
                      reducedDimName = "UMAP", runUMAP = FALSE,
23
-                     useAssay = "logcounts"){
23
+                     useAssay = "counts"){
24 24
   if(!(reducedDimName %in% names(SingleCellExperiment::reducedDims(inSCE)))){
25 25
     if (runUMAP){
26
-      inSCE <- getUMAP(inSCE, useAssay = useAssay,
27
-                       reducedDimName = reducedDimName)
26
+      inSCE <- runQuickUMAP(inSCE, useAssay = useAssay,
27
+                            reducedDimName = reducedDimName)
28 28
     } else {
29 29
       stop(reducedDimName,
30
-           " dimension not found. Run getUMAP() or set runUMAP to TRUE.")
30
+           " dimension not found. Run runUMAP() or set runUMAP to TRUE.")
31 31
     }
32 32
   }
33 33
   UMAPDf <- data.frame(SingleCellExperiment::reducedDim(inSCE,
... ...
@@ -2,7 +2,7 @@
2 2
 #' @details Wrapper function to run one of the available dimensionality
3 3
 #' reduction algorithms integrated within SCTK from \code{\link{scaterPCA}},
4 4
 #' \code{\link{runSeuratPCA}}, \code{\link{runSeuratICA}}, \code{\link{getTSNE}},
5
-#' \code{\link{runSeuratTSNE}}, \code{\link{getUMAP}} and
5
+#' \code{\link{runSeuratTSNE}}, \code{\link{runUMAP}} and
6 6
 #' \code{\link{runSeuratUMAP}}. Users can use an assay by specifying
7 7
 #' \code{useAssay}, use the assay in an altExp by specifying both
8 8
 #' \code{useAltExp} and \code{useAssay}, or use a low-dimensionality
... ...
@@ -72,7 +72,7 @@ runDimReduce <- function(inSCE,
72 72
                        useFeatureSubset = useFeatureSubset, scale = scale,
73 73
                        seed = seed, ...)
74 74
   } else if (method == "scaterUMAP") {
75
-    inSCE <- getUMAP(inSCE = inSCE, useAssay = useAssay, useAltExp = useAltExp,
75
+    inSCE <- runUMAP(inSCE = inSCE, useAssay = useAssay, useAltExp = useAltExp,
76 76
                      useReducedDim = useReducedDim,
77 77
                      useFeatureSubset = useFeatureSubset, scale = scale,
78 78
                      reducedDimName = reducedDimName, seed = seed, ...)
... ...
@@ -360,9 +360,8 @@ runSoupX <- function(inSCE,
360 360
     out <- SoupX::adjustCounts(sc, method = adjustMethod,
361 361
                                roundToInt = roundToInt, tol = tol, pCut = pCut)
362 362
     message(paste0(date(), " ... Generating UMAP"))
363
-    # Most of time `useAssay` should be "counts", thus logNorm=TRUE
364
-    inSCE <- getUMAP(inSCE, useAssay = useAssay, logNorm = TRUE,
365
-                     reducedDimName = "sampleUMAP")
363
+    inSCE <- runQuickUMAP(inSCE, useAssay = useAssay, 
364
+                          reducedDimName = "sampleUMAP")
366 365
     return(list(sc = sc, out = out,
367 366
                 umap = SingleCellExperiment::reducedDim(inSCE, "sampleUMAP")))
368 367
 }
369 368
similarity index 71%
370 369
rename from R/getUMAP.R
371 370
rename to R/runUMAP.R
... ...
@@ -1,21 +1,26 @@
1 1
 #' Run UMAP embedding with scater method
2
+#' @rdname runUMAP
2 3
 #' @description Uniform Manifold Approximation and Projection (UMAP) algorithm
3
-#' is commonly for 2D visualization of single-cell data. This function wraps the
4
-#' scater \code{\link[scater]{calculateUMAP}} function.
5
-#'
6
-#' With this funciton, users can create UMAP embedding directly from raw count
7
-#' matrix, with necessary preprocessing including normalization, scaling,
8
-#' dimension reduction all automated. Yet we still recommend having the PCA as
9
-#' input, so that the result can match with the clustering based on the same
10
-#' input PCA.
4
+#' is commonly for 2D visualization of single-cell data. These functions wrap 
5
+#' the scater \code{\link[scater]{calculateUMAP}} function.
6
+#' 
7
+#' Users can use \code{runQuickUMAP} to directly create UMAP embedding from raw
8
+#' count matrix, with necessary preprocessing including normalization, variable
9
+#' feature selection, scaling, dimension reduction all automated. Therefore, 
10
+#' \code{useReducedDim} is disabled for \code{runQuickUMAP}. 
11
+#' 
12
+#' In a complete analysis, we still recommend having dimension reduction such as
13
+#' PCA created beforehand and select proper numbers of dimensions for using
14
+#' \code{runUMAP}, so that the result can match with the clustering based on the
15
+#' same input PCA. 
11 16
 #' @param inSCE Input \linkS4class{SingleCellExperiment} object.
17
+#' @param useReducedDim The low dimension representation to use for UMAP
18
+#' computation. If \code{useAltExp} is specified, \code{useReducedDim} has to
19
+#' exist in \code{reducedDims(altExp(inSCE, useAltExp))}. Default \code{"PCA"}.
12 20
 #' @param useAssay Assay to use for UMAP computation. If \code{useAltExp} is
13 21
 #' specified, \code{useAssay} has to exist in
14 22
 #' \code{assays(altExp(inSCE, useAltExp))}. Ignored when using
15
-#' \code{useReducedDim}. Default \code{"logcounts"}.
16
-#' @param useReducedDim The low dimension representation to use for UMAP
17
-#' computation. If \code{useAltExp} is specified, \code{useReducedDim} has to
18
-#' exist in \code{reducedDims(altExp(inSCE, useAltExp))}. Default \code{NULL}.
23
+#' \code{useReducedDim}. Default \code{NULL}.
19 24
 #' @param useAltExp The subset to use for UMAP computation, usually for the
20 25
 #' selected variable features. Default \code{NULL}.
21 26
 #' @param sample Character vector. Indicates which sample each cell belongs to.
... ...
@@ -25,7 +30,7 @@
25 30
 #' coordinates obtained from this method. Default \code{"UMAP"}.
26 31
 #' @param logNorm Whether the counts will need to be log-normalized prior to
27 32
 #' generating the UMAP via \code{\link{scaterlogNormCounts}}. Ignored when using
28
-#' \code{useReducedDim}. Default \code{FALSE}.
33
+#' \code{useReducedDim}. Default \code{TRUE}.
29 34
 #' @param useFeatureSubset Subset of feature to use for dimension reduction. A
30 35
 #' character string indicating a \code{rowData} variable that stores the logical
31 36
 #' vector of HVG selection, or a vector that can subset the rows of
... ...
@@ -67,23 +72,23 @@
67 72
 #' data(scExample, package = "singleCellTK")
68 73
 #' sce <- subsetSCECols(sce, colData = "type != 'EmptyDroplet'")
69 74
 #' # Run from raw counts
70
-#' sce <- getUMAP(inSCE = sce, useAssay = "counts", logNorm = TRUE, nTop = 2000,
71
-#'                scale = TRUE, pca = TRUE)
75
+#' sce <- runQuickUMAP(sce)
72 76
 #' \dontrun{
73 77
 #' # Run from PCA
74 78
 #' sce <- scaterlogNormCounts(sce, "logcounts")
75 79
 #' sce <- runModelGeneVar(sce)
76 80
 #' sce <- scaterPCA(sce, useAssay = "logcounts",
77 81
 #'                  useFeatureSubset = "HVG_modelGeneVar2000", scale = TRUE)
78
-#' sce <- getUMAP(sce, useReducedDim = "PCA")
82
+#' sce <- runUMAP(sce, useReducedDim = "PCA")
79 83
 #' }
80 84
 #' @importFrom S4Vectors metadata<-
81
-getUMAP <- function(inSCE, useAssay = "logcounts", useReducedDim = NULL,
85
+#' @importFrom BiocParallel SerialParam
86
+runUMAP <- function(inSCE, useReducedDim = "PCA", useAssay = NULL, 
82 87
                     useAltExp = NULL, sample = NULL, reducedDimName = "UMAP",
83
-                    logNorm = FALSE, useFeatureSubset = NULL, nTop = 2000,
88
+                    logNorm = TRUE, useFeatureSubset = NULL, nTop = 2000,
84 89
                     scale = TRUE, pca = TRUE, initialDims = 25, nNeighbors = 30,
85 90
                     nIterations = 200, alpha = 1, minDist = 0.01, spread = 1,
86
-                    seed = NULL, BPPARAM = BiocParallel::SerialParam()) {
91
+                    seed = NULL, BPPARAM = SerialParam()) {
87 92
   params <- as.list(environment())
88 93
   params$inSCE <- NULL
89 94
   params$BPPARAM <- NULL
... ...
@@ -120,7 +125,7 @@ getUMAP <- function(inSCE, useAssay = "logcounts", useReducedDim = NULL,
120 125
     if (!isTRUE(pca) & !is.null(useAssay)) {
121 126
       initialDims <- NULL
122 127
     }
123
-
128
+    
124 129
     nNeighbors <- min(ncol(sceSample), nNeighbors)
125 130
     message(paste0(date(), " ... Computing Scater UMAP for sample '",
126 131
                    samples[i], "'."))
... ...
@@ -145,3 +150,39 @@ getUMAP <- function(inSCE, useAssay = "logcounts", useReducedDim = NULL,
145 150
   metadata(inSCE)$sctk$runDimReduce$embedding[[reducedDimName]] <- params
146 151
   return(inSCE)
147 152
 }
153
+
154
+#' @rdname runUMAP
155
+#' @param ... Parameters passed to \code{runUMAP}
156
+#' @importFrom BiocParallel SerialParam
157
+#' @export
158
+runQuickUMAP <- function(inSCE, useAssay = "counts", sample = "sample", ...) {
159
+  args <- list(...)
160
+  if (!is.null(args$useReducedDim)) {
161
+    warning("Forcing `useReducedDim` to be `NULL`. Please use `runUMAP` for ",
162
+            "using reducedDim.")
163
+  }
164
+  args$useReducedDim <- NULL
165
+  args <- c(list(inSCE = inSCE, useAssay = useAssay, useReducedDim = NULL), 
166
+            args)
167
+  inSCE <- do.call("runUMAP", args = args)
168
+  return(inSCE)
169
+}
170
+
171
+#' @rdname runUMAP
172
+#' @export
173
+#' @importFrom BiocParallel SerialParam
174
+getUMAP <- function(inSCE, useReducedDim = "PCA", useAssay = NULL, 
175
+                    useAltExp = NULL, sample = NULL, reducedDimName = "UMAP",
176
+                    logNorm = TRUE, useFeatureSubset = NULL, nTop = 2000,
177
+                    scale = TRUE, pca = TRUE, initialDims = 25, nNeighbors = 30,
178
+                    nIterations = 200, alpha = 1, minDist = 0.01, spread = 1,
179
+                    seed = NULL, BPPARAM = SerialParam()) {
180
+  .Deprecated("runUMAP")
181
+  runUMAP(inSCE, useReducedDim = useReducedDim, useAssay = useAssay, 
182
+          useAltExp = useAltExp, sample = sample, 
183
+          reducedDimName = reducedDimName,
184
+          logNorm = logNorm, useFeatureSubset = useFeatureSubset, nTop = nTop,
185
+          scale = scale, pca = pca, initialDims = initialDims, 
186
+          nNeighbors = nNeighbors, nIterations = nIterations, alpha = alpha, 
187
+          minDist = minDist, spread = spread, seed = seed, BPPARAM = BPPARAM)
188
+}
... ...
@@ -144,8 +144,7 @@ A wrapper function which visualizes outputs from the
144 144
 \examples{
145 145
 data(scExample, package="singleCellTK")
146 146
 sce <- subsetSCECols(sce, colData = "type != 'EmptyDroplet'")
147
-sce <- getUMAP(inSCE=sce, useAssay="counts", logNorm=TRUE, 
148
-               reducedDimName="UMAP")
147
+sce <- runQuickUMAP(sce)
149 148
 sce <- runBcds(sce)
150 149
 plotBcdsResults(inSCE=sce, reducedDimName="UMAP")
151 150
 }
... ...
@@ -144,8 +144,7 @@ A wrapper function which visualizes outputs from the
144 144
 \examples{
145 145
 data(scExample, package="singleCellTK")
146 146
 sce <- subsetSCECols(sce, colData = "type != 'EmptyDroplet'")
147
-sce <- getUMAP(inSCE=sce, useAssay="counts", logNorm=TRUE, 
148
-               reducedDimName="UMAP")
147
+sce <- runQuickUMAP(sce)
149 148
 sce <- runCxds(sce)
150 149
 plotCxdsResults(inSCE=sce, reducedDimName="UMAP")
151 150
 }
... ...
@@ -144,8 +144,7 @@ A wrapper function which visualizes outputs from the
144 144
 \examples{
145 145
 data(scExample, package="singleCellTK")
146 146
 sce <- subsetSCECols(sce, colData = "type != 'EmptyDroplet'")
147
-sce <- getUMAP(inSCE=sce, useAssay="counts", logNorm=TRUE, 
148
-               reducedDimName="UMAP")
147
+sce <- runQuickUMAP(sce)
149 148
 sce <- runDoubletFinder(sce)
150 149
 plotDoubletFinderResults(inSCE=sce, reducedDimName="UMAP")
151 150
 }
... ...
@@ -144,8 +144,7 @@ A wrapper function which visualizes outputs from the
144 144
 \examples{
145 145
 data(scExample, package="singleCellTK")
146 146
 sce <- subsetSCECols(sce, colData = "type != 'EmptyDroplet'")
147
-sce <- getUMAP(inSCE=sce, useAssay="counts", logNorm=TRUE, 
148
-               reducedDimName="UMAP")
147
+sce <- runQuickUMAP(sce)
149 148
 sce <- runScDblFinder(sce)
150 149
 plotScDblFinderResults(inSCE=sce, reducedDimName="UMAP")
151 150
 }
... ...
@@ -144,8 +144,7 @@ A wrapper function which visualizes outputs from the
144 144
 \examples{
145 145
 data(scExample, package="singleCellTK")
146 146
 sce <- subsetSCECols(sce, colData = "type != 'EmptyDroplet'")
147
-sce <- getUMAP(inSCE=sce, useAssay="counts", logNorm=TRUE, 
148
-               reducedDimName="UMAP")
147
+sce <- runQuickUMAP(sce)
149 148
 sce <- runCxdsBcdsHybrid(sce)
150 149
 plotScdsHybridResults(inSCE=sce, reducedDimName="UMAP")
151 150
 }
... ...
@@ -145,8 +145,7 @@ A wrapper function which visualizes outputs from the
145 145
 data(scExample, package="singleCellTK")
146 146
 \dontrun{
147 147
 sce <- subsetSCECols(sce, colData = "type != 'EmptyDroplet'")
148
-sce <- getUMAP(inSCE=sce, useAssay="counts", logNorm=TRUE, 
149
-               reducedDimName="UMAP")
148
+sce <- runQuickUMAP(sce)
150 149
 sce <- runScrublet(sce)
151 150
 plotScrubletResults(inSCE=sce, reducedDimName="UMAP")
152 151
 }
... ...
@@ -10,7 +10,7 @@ plotUMAP(
10 10
   shape = NULL,
11 11
   reducedDimName = "UMAP",
12 12
   runUMAP = FALSE,
13
-  useAssay = "logcounts"
13
+  useAssay = "counts"
14 14
 )
15 15
 }
16 16
 \arguments{
... ...
@@ -38,6 +38,6 @@ Plot UMAP results either on already run results or run first and then plot.
38 38
 \examples{
39 39
 data(scExample, package = "singleCellTK")
40 40
 sce <- subsetSCECols(sce, colData = "type != 'EmptyDroplet'")
41
-sce <- getUMAP(inSCE = sce, useAssay = "counts", reducedDimName = "UMAP")
41
+sce <- runQuickUMAP(sce)
42 42
 plotUMAP(sce)
43 43
 }
... ...
@@ -35,7 +35,7 @@ data(scExample, package = "singleCellTK")
35 35
 sce <- subsetSCECols(sce, colData = "type != 'EmptyDroplet'")
36 36
 \dontrun{
37 37
 sce <- runDecontX(sce)
38
-sce <- getUMAP(sce, useAssay = "counts", logNorm = TRUE)
38
+sce <- runQuickUMAP(sce)
39 39
 reportQCTool(inSCE = sce, algorithm = "DecontX")
40 40
 }
41 41
 }
... ...
@@ -67,7 +67,7 @@ Generic Wrapper function for running dimensionality reduction
67 67
 Wrapper function to run one of the available dimensionality
68 68
 reduction algorithms integrated within SCTK from \code{\link{scaterPCA}},
69 69
 \code{\link{runSeuratPCA}}, \code{\link{runSeuratICA}}, \code{\link{getTSNE}},
70
-\code{\link{runSeuratTSNE}}, \code{\link{getUMAP}} and
70
+\code{\link{runSeuratTSNE}}, \code{\link{runUMAP}} and
71 71
 \code{\link{runSeuratUMAP}}. Users can use an assay by specifying
72 72
 \code{useAssay}, use the assay in an altExp by specifying both
73 73
 \code{useAltExp} and \code{useAssay}, or use a low-dimensionality
74 74
similarity index 73%
75 75
rename from man/getUMAP.Rd
76 76
rename to man/runUMAP.Rd
... ...
@@ -1,17 +1,43 @@
1 1
 % Generated by roxygen2: do not edit by hand
2
-% Please edit documentation in R/getUMAP.R
3
-\name{getUMAP}
2
+% Please edit documentation in R/runUMAP.R
3
+\name{runUMAP}
4
+\alias{runUMAP}
5
+\alias{runQuickUMAP}
4 6
 \alias{getUMAP}
5 7
 \title{Run UMAP embedding with scater method}
6 8
 \usage{
9
+runUMAP(
10
+  inSCE,
11
+  useReducedDim = "PCA",
12
+  useAssay = NULL,
13
+  useAltExp = NULL,
14
+  sample = NULL,
15
+  reducedDimName = "UMAP",
16
+  logNorm = TRUE,
17
+  useFeatureSubset = NULL,
18
+  nTop = 2000,
19
+  scale = TRUE,
20
+  pca = TRUE,
21
+  initialDims = 25,
22
+  nNeighbors = 30,
23
+  nIterations = 200,
24
+  alpha = 1,
25
+  minDist = 0.01,
26
+  spread = 1,
27
+  seed = NULL,
28
+  BPPARAM = SerialParam()
29
+)
30
+
31
+runQuickUMAP(inSCE, useAssay = "counts", sample = "sample", ...)
32
+
7 33
 getUMAP(
8 34
   inSCE,
9
-  useAssay = "logcounts",
10
-  useReducedDim = NULL,
35
+  useReducedDim = "PCA",
36
+  useAssay = NULL,
11 37
   useAltExp = NULL,
12 38
   sample = NULL,
13 39
   reducedDimName = "UMAP",
14
-  logNorm = FALSE,
40
+  logNorm = TRUE,
15 41
   useFeatureSubset = NULL,
16 42
   nTop = 2000,
17 43
   scale = TRUE,
... ...
@@ -23,20 +49,20 @@ getUMAP(
23 49
   minDist = 0.01,
24 50
   spread = 1,
25 51
   seed = NULL,
26
-  BPPARAM = BiocParallel::SerialParam()
52
+  BPPARAM = SerialParam()
27 53
 )
28 54
 }
29 55
 \arguments{
30 56
 \item{inSCE}{Input \linkS4class{SingleCellExperiment} object.}
31 57
 
58
+\item{useReducedDim}{The low dimension representation to use for UMAP
59
+computation. If \code{useAltExp} is specified, \code{useReducedDim} has to
60
+exist in \code{reducedDims(altExp(inSCE, useAltExp))}. Default \code{"PCA"}.}
61
+
32 62
 \item{useAssay}{Assay to use for UMAP computation. If \code{useAltExp} is
33 63
 specified, \code{useAssay} has to exist in
34 64
 \code{assays(altExp(inSCE, useAltExp))}. Ignored when using
35
-\code{useReducedDim}. Default \code{"logcounts"}.}
36
-
37
-\item{useReducedDim}{The low dimension representation to use for UMAP
38
-computation. If \code{useAltExp} is specified, \code{useReducedDim} has to
39
-exist in \code{reducedDims(altExp(inSCE, useAltExp))}. Default \code{NULL}.}
65
+\code{useReducedDim}. Default \code{NULL}.}
40 66
 
41 67
 \item{useAltExp}{The subset to use for UMAP computation, usually for the
42 68
 selected variable features. Default \code{NULL}.}
... ...
@@ -50,7 +76,7 @@ coordinates obtained from this method. Default \code{"UMAP"}.}
50 76
 
51 77
 \item{logNorm}{Whether the counts will need to be log-normalized prior to
52 78
 generating the UMAP via \code{\link{scaterlogNormCounts}}. Ignored when using
53
-\code{useReducedDim}. Default \code{FALSE}.}
79
+\code{useReducedDim}. Default \code{TRUE}.}
54 80
 
55 81
 \item{useFeatureSubset}{Subset of feature to use for dimension reduction. A
56 82
 character string indicating a \code{rowData} variable that stores the logical
... ...
@@ -97,6 +123,8 @@ Default \code{NULL} will use global seed in use by the R environment.}
97 123
 
98 124
 \item{BPPARAM}{A \linkS4class{BiocParallelParam} object specifying whether
99 125
 the PCA should be parallelized.}
126
+
127
+\item{...}{Parameters passed to \code{runUMAP}}
100 128
 }
101 129
 \value{
102 130
 A \linkS4class{SingleCellExperiment} object with UMAP computation
... ...
@@ -104,27 +132,30 @@ updated in \code{reducedDim(inSCE, reducedDimName)}.
104 132
 }
105 133
 \description{
106 134
 Uniform Manifold Approximation and Projection (UMAP) algorithm
107
-is commonly for 2D visualization of single-cell data. This function wraps the
108
-scater \code{\link[scater]{calculateUMAP}} function.
109
-
110
-With this funciton, users can create UMAP embedding directly from raw count
111
-matrix, with necessary preprocessing including normalization, scaling,
112
-dimension reduction all automated. Yet we still recommend having the PCA as
113
-input, so that the result can match with the clustering based on the same
114
-input PCA.
135
+is commonly for 2D visualization of single-cell data. These functions wrap 
136
+the scater \code{\link[scater]{calculateUMAP}} function.
137
+
138
+Users can use \code{runQuickUMAP} to directly create UMAP embedding from raw
139
+count matrix, with necessary preprocessing including normalization, variable
140
+feature selection, scaling, dimension reduction all automated. Therefore, 
141
+\code{useReducedDim} is disabled for \code{runQuickUMAP}. 
142
+
143
+In a complete analysis, we still recommend having dimension reduction such as
144
+PCA created beforehand and select proper numbers of dimensions for using
145
+\code{runUMAP}, so that the result can match with the clustering based on the
146
+same input PCA.
115 147
 }
116 148
 \examples{
117 149
 data(scExample, package = "singleCellTK")
118 150
 sce <- subsetSCECols(sce, colData = "type != 'EmptyDroplet'")
119 151
 # Run from raw counts
120
-sce <- getUMAP(inSCE = sce, useAssay = "counts", logNorm = TRUE, nTop = 2000,
121
-               scale = TRUE, pca = TRUE)
152
+sce <- runQuickUMAP(sce)
122 153
 \dontrun{
123 154
 # Run from PCA
124 155
 sce <- scaterlogNormCounts(sce, "logcounts")
125 156
 sce <- runModelGeneVar(sce)
126 157
 sce <- scaterPCA(sce, useAssay = "logcounts",
127 158
                  useFeatureSubset = "HVG_modelGeneVar2000", scale = TRUE)
128
-sce <- getUMAP(sce, useReducedDim = "PCA")
159
+sce <- runUMAP(sce, useReducedDim = "PCA")
129 160
 }
130 161
 }
... ...
@@ -45,32 +45,33 @@ test_that(desc = "Testing scaterPCA", {
45 45
 
46 46
 test_that(desc = "Testing scater UMAP", {
47 47
     sce <- scaterPCA(sce, useFeatureSubset = "hvg", seed = 12345, reducedDimName = "PCA1")
48
-    sce <- getUMAP(sce, useReducedDim = "PCA1", reducedDimName = "UMAP1")
48
+    sce <- runUMAP(sce, useReducedDim = "PCA1", reducedDimName = "UMAP1")
49 49
     testthat::expect_true("UMAP1" %in% reducedDimNames(sce))
50
-    sce <- getUMAP(sce, useAssay = "hvgAltExplogcounts", useAltExp = "hvgAltExp",
50
+    sce <- runUMAP(sce, useAssay = "hvgAltExplogcounts", useReducedDim = NULL,
51
+                   useAltExp = "hvgAltExp",
51 52
                    reducedDimName = "UMAP2")
52 53
     testthat::expect_true("UMAP2" %in% reducedDimNames(sce))
53 54
     # TODO: Still some runable conditions
54 55
     expect_error({
55
-        getUMAP(inSCE = 1)
56
+        runUMAP(inSCE = 1)
56 57
     }, "`inSCE` should be a SingleCellExperiment Object.")
57 58
     expect_error({
58
-        getUMAP(sce, useAssay = NULL, useReducedDim = NULL)
59
+        runUMAP(sce, useAssay = NULL, useReducedDim = NULL)
59 60
     }, "Either `useAssay` or `useReducedDim` has to be specified.")
60 61
     expect_error({
61
-        getUMAP(sce, useAltExp = "altexp")
62
+        runUMAP(sce, useAltExp = "altexp")
62 63
     }, "Specified `useAltExp` 'altexp' not found.")
63 64
     expect_error({
64
-        getUMAP(sce, useReducedDim = "TSNE")
65
+        runUMAP(sce, useReducedDim = "TSNE")
65 66
     }, "Specified `useReducedDim` 'TSNE' not found.")
66 67
     expect_error({
67
-        getUMAP(sce, useAssay = "TSNE")
68
+        runUMAP(sce, useAssay = "TSNE", useReducedDim = NULL)
68 69
     }, regexp = "Specified `useAssay` 'TSNE' not found.")
69 70
     expect_error({
70
-        getUMAP(sce, sample = "batch")
71
+        runUMAP(sce, useReducedDim = "PCA1", sample = "batch")
71 72
     }, regexp = "Specified variable 'batch'")
72 73
     expect_error({
73
-        getUMAP(sce, sample = letters)
74
+        runUMAP(sce, useReducedDim = "PCA1", sample = letters)
74 75
     }, regexp = "Invalid variable length")
75 76
 
76 77
     p1 <- plotUMAP(sce, reducedDimName = "UMAP1", colorBy = "type", shape = "type")
... ...
@@ -100,12 +101,6 @@ test_that(desc = "Testing Rtsne TSNE", {
100 101
     expect_error({
101 102
         getTSNE(sce, useAltExp = "altexp")
102 103
     }, "Specified `useAltExp` 'altexp' not found.")
103
-    expect_error({
104
-        getUMAP(sce, useReducedDim = "TSNE")
105
-    }, "Specified `useReducedDim` 'TSNE' not found.")
106
-    expect_error({
107
-        getUMAP(sce, useAssay = "TSNE")
108
-    }, regexp = "Specified `useAssay` 'TSNE' not found.")
109 104
 
110 105
     p1 <- plotTSNE(sce, reducedDimName = "TSNE1", colorBy = "type", shape = "type")
111 106
     p2 <- plotTSNE(sce, reducedDimName = "TSNE3", runTSNE = TRUE)
... ...
@@ -5,13 +5,8 @@ data(scExample, package = "singleCellTK")
5 5
 sceDroplet <- sce
6 6
 sce <- subsetSCECols(sce, colData = "type != 'EmptyDroplet'")
7 7
 sampleVector <- c(rep("Sample1", 100), rep("Sample2", 95))
8
-sceres <- getUMAP(inSCE = sce, useAssay = "counts", logNorm = TRUE, sample = sampleVector, nNeighbors = 10, reducedDimName = "UMAP",
9
-                nIterations = 20, alpha = 1, minDist = 0.01, pca = TRUE, initialDims = 20)
10
-
11
-test_that(desc = "Testing getUMAP", {
12
-        expect_equal(names(reducedDims(sceres)), "UMAP")
13
-	expect_equal(nrow(reducedDim(sceres, "UMAP")), ncol(sce))
14
-})
8
+sceres <- runQuickUMAP(inSCE = sce, sample = sampleVector, nNeighbors = 10,
9
+                nIterations = 20, alpha = 1, minDist = 0.01, initialDims = 20)
15 10
 
16 11
 test_that(desc = "Testing plotSCEScatter functions", {
17 12
     p1 <- plotSCEScatter(inSCE = sceres, legendTitle = NULL,