Merge pull request #2868 from satijalab/develop

Seurat v3.1.5

DESCRIPTION

@@ -1,8 +1,8 @@
 Package: Seurat
-Version: 3.1.4
-Date: 2020-02-26
+Version: 3.1.5
+Date: 2020-04-14
 Title: Tools for Single Cell Genomics
-Description: A toolkit for quality control, analysis, and exploration of single cell RNA sequencing data. 'Seurat' aims to enable users to identify and interpret sources of heterogeneity from single cell transcriptomic measurements, and to integrate diverse types of single cell data. See Satija R, Farrell J, Gennert D, et al (2015) <doi:10.1038/nbt.3192>, Macosko E, Basu A, Satija R, et al (2015) <doi:10.1016/j.cell.2015.05.002>, and Butler A and Satija R (2017) <doi:10.1101/164889> for more details. Please note:  SDMTools is available is available from the CRAN archives with install.packages("https://cran.rstudio.com//src/contrib/Archive/SDMTools/SDMTools_1.1-221.2.tar.gz", repos = NULL); it is not in the standard repositories.
+Description: A toolkit for quality control, analysis, and exploration of single cell RNA sequencing data. 'Seurat' aims to enable users to identify and interpret sources of heterogeneity from single cell transcriptomic measurements, and to integrate diverse types of single cell data. See Satija R, Farrell J, Gennert D, et al (2015) <doi:10.1038/nbt.3192>, Macosko E, Basu A, Satija R, et al (2015) <doi:10.1016/j.cell.2015.05.002>, and Stuart T, Butler A, et al (2019) <doi:10.1016/j.cell.2019.05.031> for more details. Please note:  SDMTools is available is available from the CRAN archives with install.packages(<"https://cran.rstudio.com//src/contrib/Archive/SDMTools/SDMTools_1.1-221.2.tar.gz">, repos = NULL); it is not in the standard repositories.
 Authors@R: c(
   person(given = 'Rahul', family = 'Satija', email = 'rsatija@nygenome.org', role = 'aut', comment = c(ORCID = '0000-0001-9448-8833')),
   person(given = 'Andrew', family = 'Butler', email = 'abutler@nygenome.org', role = 'aut', comment = c(ORCID = '0000-0003-3608-0463')),
@@ -42,7 +42,6 @@ Imports:
     lmtest,
     MASS,
     Matrix (>= 1.2-14),
-    metap,
     patchwork,
     pbapply,
     plotly,
@@ -81,7 +80,7 @@ Collate:
     'tree.R'
     'utilities.R'
     'zzz.R'
-RoxygenNote: 7.0.2
+RoxygenNote: 7.1.0
 Encoding: UTF-8
 biocViews:
 Suggests:
@@ -101,4 +100,6 @@ Suggests:
     rtracklayer,
     monocle,
     Biobase,
-    VGAM
+    VGAM,
+    limma,
+    metap

NAMESPACE

@@ -15,6 +15,7 @@ S3method("Key<-",Assay)
 S3method("Key<-",DimReduc)
 S3method("Loadings<-",DimReduc)
 S3method("Misc<-",Assay)
+S3method("Misc<-",DimReduc)
 S3method("Misc<-",Seurat)
 S3method("Project<-",Seurat)
 S3method("Tool<-",Seurat)
@@ -70,6 +71,7 @@ S3method(Key,Seurat)
 S3method(Loadings,DimReduc)
 S3method(Loadings,Seurat)
 S3method(Misc,Assay)
+S3method(Misc,DimReduc)
 S3method(Misc,Seurat)
 S3method(NormalizeData,Assay)
 S3method(NormalizeData,Seurat)
@@ -409,6 +411,7 @@ importFrom(ggplot2,guides)
 importFrom(ggplot2,labs)
 importFrom(ggplot2,layer)
 importFrom(ggplot2,margin)
+importFrom(ggplot2,position_jitterdodge)
 importFrom(ggplot2,scale_color_brewer)
 importFrom(ggplot2,scale_color_distiller)
 importFrom(ggplot2,scale_color_gradient)
@@ -469,7 +472,6 @@ importFrom(igraph,plot.igraph)
 importFrom(irlba,irlba)
 importFrom(leiden,leiden)
 importFrom(lmtest,lrtest)
-importFrom(metap,minimump)
 importFrom(methods,"slot<-")
 importFrom(methods,.hasSlot)
 importFrom(methods,as)
@@ -496,6 +498,9 @@ importFrom(reticulate,py_module_available)
 importFrom(reticulate,py_set_seed)
 importFrom(reticulate,tuple)
 importFrom(rlang,"!!")
+importFrom(rlang,enquo)
+importFrom(rlang,eval_tidy)
+importFrom(rlang,is_quosure)
 importFrom(rsvd,rsvd)
 importFrom(scales,hue_pal)
 importFrom(scales,zero_range)
@@ -557,4 +562,5 @@ importFrom(utils,setTxtProgressBar)
 importFrom(utils,txtProgressBar)
 importFrom(utils,write.table)
 importFrom(uwot,umap)
+importFrom(uwot,umap_transform)
 useDynLib(Seurat)

NEWS.md

@@ -2,6 +2,27 @@
 All notable changes to Seurat will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 
+## [3.1.5] - 2020-04-14
+### Added
+- New `scale` parameter in `DotPlot` 
+- New `keep.sparse parameter in `CreateGeneActivityMatrix` for a more memory efficient option
+- Added ability to store model learned by UMAP and project new data
+- New `stip.suffix` option in `Read10X`
+- Added `group.by` parameter to `FeatureScatter`
+
+### Changes
+- Replace wilcox.test with limma implementation for a faster FindMarkers default method
+- Better point separation for `VlnPlot`s when using the `split.by` option
+- Efficiency improvements for anchor pairing
+- Deprecate redundant `sort.cell` parameter in `FeaturePlot`
+- Fixes to ensure correct class of Matrix passed to c++ functions
+- Fixes for underscores in ident labels for `DotPlot`
+- Ensure preservation of matrix dimnames in `SampleUMI`
+- Fix non-standard evaluation problems in `subset` and `WhichCells`
+- Default split violin option is now a multi group option
+- Preserve alpha in `FeaturePlot` when using `blend`
+- Update `assay.used` slot for `DimReduc`s when Assay is renamed
+
 ## [3.1.4] - 2020-02-20
 ### Changes 
 - Fixes to `DoHeatmap` to remain compatible with ggplot2 v3.3

R/differential_expression.R

@@ -210,8 +210,6 @@ FindAllMarkers <- function(
 #' associated output column (e.g. CTRL_p_val). If only one group is tested in the grouping.var, max
 #' and combined p-values are not returned.
 #'
-#' @importFrom metap minimump
-#'
 #' @export
 #'
 #' @examples
@@ -229,10 +227,23 @@ FindConservedMarkers <- function(
   grouping.var,
   assay = 'RNA',
   slot = 'data',
-  meta.method = minimump,
+  meta.method = metap::minimump,
   verbose = TRUE,
   ...
 ) {
+  metap.installed <- PackageCheck("metap", error = FALSE)
+  if (!metap.installed[1]) {
+    stop(
+      "Please install the metap package to use FindConservedMarkers.",
+      "\nThis can be accomplished with the following commands: ",
+      "\n----------------------------------------",
+      "\ninstall.packages('BiocManager')",
+      "\nBiocManager::install('multtest')",
+      "\ninstall.packages('metap')",
+      "\n----------------------------------------",
+      call. = FALSE
+    )
+  }
   if (!is.function(x = meta.method)) {
     stop("meta.method should be a function from the metap package. Please see https://cran.r-project.org/web/packages/metap/metap.pdf for a detailed description of the available functions.")
   }
@@ -354,12 +365,13 @@ FindConservedMarkers <- function(
         return(meta.method(x)$p)
       }
     ))
-    colnames(x = combined.pval) <- paste0(
-      as.character(x = formals()$meta.method),
-      "_p_val"
-    )
+    meta.method.name <- as.character(x = formals()$meta.method)
+    if (length(x = meta.method.name) == 3) {
+      meta.method.name <- meta.method.name[3]
+    }
+    colnames(x = combined.pval) <- paste0(meta.method.name, "_p_val")
     markers.combined <- cbind(markers.combined, combined.pval)
-    markers.combined <- markers.combined[order(markers.combined[, paste0(as.character(x = formals()$meta.method), "_p_val")]), ]
+    markers.combined <- markers.combined[order(markers.combined[, paste0(meta.method.name, "_p_val")]), ]
   } else {
     warning("Only a single group was tested", call. = FALSE, immediate. = TRUE)
   }
@@ -1505,7 +1517,9 @@ RegularizedTheta <- function(cm, latent.data, min.theta = 0.01, bin.size = 128)
 # Differential expression using Wilcoxon Rank Sum
 #
 # Identifies differentially expressed genes between two groups of cells using
-# a Wilcoxon Rank Sum test
+# a Wilcoxon Rank Sum test. Makes use of limma::rankSumTestWithCorrelation for a
+# more efficient implementation of the wilcoxon test. Thanks to Yunshun Chen and
+# Gordon Smyth for suggesting the limma implementation.
 #
 # @param data.use Data matrix to test
 # @param cells.1 Group 1 cells
@@ -1535,21 +1549,47 @@ WilcoxDETest <- function(
   verbose = TRUE,
   ...
 ) {
-  group.info <- data.frame(row.names = c(cells.1, cells.2))
-  group.info[cells.1, "group"] <- "Group1"
-  group.info[cells.2, "group"] <- "Group2"
-  group.info[, "group"] <- factor(x = group.info[, "group"])
-  data.use <- data.use[, rownames(x = group.info), drop = FALSE]
+  data.use <- data.use[, c(cells.1, cells.2), drop = FALSE]
+  j <- seq_len(length.out = length(x = cells.1))
   my.sapply <- ifelse(
     test = verbose && nbrOfWorkers() == 1,
     yes = pbsapply,
     no = future_sapply
   )
-  p_val <- my.sapply(
-    X = 1:nrow(x = data.use),
-    FUN = function(x) {
-      return(wilcox.test(data.use[x, ] ~ group.info[, "group"], ...)$p.value)
+  limma.check <- PackageCheck("limma", error = FALSE)
+  if (limma.check[1]) {
+    p_val <- my.sapply(
+      X = 1:nrow(x = data.use),
+      FUN = function(x) {
+        return(min(2 * min(limma::rankSumTestWithCorrelation(index = j, statistics = data.use[x, ])), 1))
+      }
+    )
+  } else {
+    if (getOption('Seurat.limma.wilcox.msg', TRUE)) {
+      message(
+        "For a more efficient implementation of the Wilcoxon Rank Sum Test,", 
+        "\n(default method for FindMarkers) please install the limma package",
+        "\n--------------------------------------------",
+        "\ninstall.packages('BiocManager')",
+        "\nBiocManager::install('limma')",
+        "\n--------------------------------------------",
+        "\nAfter installation of limma, Seurat will automatically use the more ",
+        "\nefficient implementation (no further action necessary).",
+        "\nThis message will be shown once per session"
+      )
+      options(Seurat.limma.wilcox.msg = FALSE)
     }
-  )
+    group.info <- data.frame(row.names = c(cells.1, cells.2))
+    group.info[cells.1, "group"] <- "Group1"
+    group.info[cells.2, "group"] <- "Group2"
+    group.info[, "group"] <- factor(x = group.info[, "group"])
+    data.use <- data.use[, rownames(x = group.info), drop = FALSE]
+    p_val <- my.sapply(
+      X = 1:nrow(x = data.use),
+      FUN = function(x) {
+        return(wilcox.test(data.use[x, ] ~ group.info[, "group"], ...)$p.value)
+      }
+    )
+  }
   return(data.frame(p_val, row.names = rownames(x = data.use)))
 }

R/dimensional_reduction.R

@@ -65,6 +65,10 @@ JackStraw <- function(
     my.sapply <- future_sapply
   }
   assay <- assay %||% DefaultAssay(object = object)
+  if (IsSCT(assay = object[[assay]])) {
+    stop("JackStraw cannot be run on SCTransform-normalized data.
+         Please supply a non-SCT assay.")
+  }
   if (dims > length(x = object[[reduction]])) {
     dims <- length(x = object[[reduction]])
     warning("Number of dimensions specified is greater than those available. Setting dims to ", dims, " and continuing", immediate. = TRUE)
@@ -1137,7 +1141,7 @@ RunTSNE.Seurat <- function(
 }
 
 #' @importFrom reticulate py_module_available py_set_seed import
-#' @importFrom uwot umap
+#' @importFrom uwot umap umap_transform
 #' @importFrom future nbrOfWorkers
 #'
 #' @rdname RunUMAP
@@ -1146,6 +1150,7 @@ RunTSNE.Seurat <- function(
 #'
 RunUMAP.default <- function(
   object,
+  reduction.model = NULL,
   assay = NULL,
   umap.method = 'uwot',
   n.neighbors = 30L,
@@ -1245,8 +1250,75 @@ RunUMAP.default <- function(
         verbose = verbose
       )
     },
+    'uwot-learn' = {
+      if (metric == 'correlation') {
+        warning(
+          "UWOT does not implement the correlation metric, using cosine instead",
+          call. = FALSE,
+          immediate. = TRUE
+        )
+        metric <- 'cosine'
+      }
+      umap(
+        X = object,
+        n_threads = nbrOfWorkers(),
+        n_neighbors = as.integer(x = n.neighbors),
+        n_components = as.integer(x = n.components),
+        metric = metric,
+        n_epochs = n.epochs,
+        learning_rate = learning.rate,
+        min_dist = min.dist,
+        spread = spread,
+        set_op_mix_ratio = set.op.mix.ratio,
+        local_connectivity = local.connectivity,
+        repulsion_strength = repulsion.strength,
+        negative_sample_rate = negative.sample.rate,
+        a = a,
+        b = b,
+        fast_sgd = uwot.sgd,
+        verbose = verbose,
+        ret_model = TRUE
+      )
+    },
+    'uwot-predict' = {
+      if (metric == 'correlation') {
+        warning(
+          "UWOT does not implement the correlation metric, using cosine instead",
+          call. = FALSE,
+          immediate. = TRUE
+        )
+        metric <- 'cosine'
+      }
+      if (is.null(x = reduction.model) || !inherits(x = reduction.model, what = 'DimReduc')) {
+        stop(
+          "If using uwot-predict, please pass a DimReduc object with the model stored to reduction.model.",
+          call. = FALSE
+        )
+      }
+      model <- reduction.model %||% Misc(
+        object = reduction.model,
+        slot = "model"
+      )
+      if (length(x = model) == 0) {
+        stop(
+          "The provided reduction.model does not have a model stored. Please try running umot-learn on the object first",
+          call. = FALSE
+        )
+      }
+      umap_transform(
+        X = object,
+        model = model,
+        n_threads = nbrOfWorkers(),
+        n_epochs = n.epochs,
+        verbose = verbose
+      )
+    },
     stop("Unknown umap method: ", umap.method, call. = FALSE)
   )
+  if (umap.method == 'uwot-learn') {
+    umap.model <- umap.output
+    umap.output <- umap.output$embedding
+  }
   colnames(x = umap.output) <- paste0(reduction.key, 1:ncol(x = umap.output))
   if (inherits(x = object, what = 'dist')) {
     rownames(x = umap.output) <- attr(x = object, "Labels")
@@ -1259,6 +1331,9 @@ RunUMAP.default <- function(
     assay = assay,
     global = TRUE
   )
+  if (umap.method == 'uwot-learn') {
+    Misc(umap.reduction, slot = "model") <- umap.model
+  }
   return(umap.reduction)
 }
 
@@ -1350,6 +1425,7 @@ RunUMAP.Graph <- function(
   return(umap)
 }
 
+#' @param reduction.model \code{DimReduc} object that contains the umap model
 #' @param dims Which dimensions to use as input features, used only if
 #' \code{features} is NULL
 #' @param reduction Which dimensional reduction (PCA or ICA) to use for the
@@ -1363,6 +1439,7 @@ RunUMAP.Graph <- function(
 #' @param umap.method UMAP implementation to run. Can be
 #' \describe{
 #'   \item{\code{uwot}:}{Runs umap via the uwot R package}
+#'   \item{\code{uwot-learn}:}{Runs umap via the uwot R package and return the learned umap model}
 #'   \item{\code{umap-learn}:}{Run the Seurat wrapper of the python umap-learn package}
 #' }
 #' @param n.neighbors This determines the number of neighboring points used in
@@ -1423,6 +1500,7 @@ RunUMAP.Graph <- function(
 #'
 RunUMAP.Seurat <- function(
   object,
+  reduction.model = NULL,
   dims = NULL,
   reduction = 'pca',
   features = NULL,
@@ -1487,6 +1565,7 @@ RunUMAP.Seurat <- function(
   }
   object[[reduction.name]] <- RunUMAP(
     object = data.use,
+    reduction.model = reduction.model,
     assay = assay,
     umap.method = umap.method,
     n.neighbors = n.neighbors,