Merge pull request #4630 from lldelisle/densMAP

support densmap

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: Seurat
-Version: 4.0.3.9002
-Date: 2021-07-08
+Version: 4.0.3.9003
+Date: 2021-07-09
 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>, Stuart T, Butler A, et al (2019) <doi:10.1016/j.cell.2019.05.031>, and Hao, Hao, et al (2020) <doi:10.1101/2020.10.12.335331> for more details.
 Authors@R: c(

NEWS.md

@@ -1,6 +1,7 @@
 ## Unreleased
 ## Added
 - Add `reduction` parameter to `BuildClusterTree()` ([#4598](https://github.com/satijalab/seurat/issues/4598))
+- Add DensMAP option to `RunUMAP()` ([4630](https://github.com/satijalab/seurat/pull/4630))
 
 ## Changes
 - Warn and continue rather than erroring if not all features are available in `FindSpatiallyVariableFeatures()` ([#4611](https://github.com/satijalab/seurat/issues/4611))

R/dimensional_reduction.R

@@ -1210,6 +1210,10 @@ RunUMAP.default <- function(
   seed.use = 42,
   metric.kwds = NULL,
   angular.rp.forest = FALSE,
+  densmap = FALSE,
+  dens.lambda = 2,
+  dens.frac = 0.3,
+  dens.var.shift = 0.1,
   verbose = TRUE,
   ...
 ) {
@@ -1232,6 +1236,10 @@ RunUMAP.default <- function(
     umap.method <- "uwot"
     return.model <- TRUE
   }
+  if (densmap && umap.method != 'umap-learn'){
+    warning("densmap is only supported by umap-learn method. Method is changed to 'umap-learn'")
+    umap.method <- 'umap-learn'
+  }
   if (return.model) {
     if (verbose) {
       message("UMAP will return its model")
@@ -1261,7 +1269,12 @@ RunUMAP.default <- function(
         n.epochs <- as.integer(x = n.epochs)
       }
       umap_import <- import(module = "umap", delay_load = TRUE)
-      umap <- umap_import$UMAP(
+      if (densmap &&
+          numeric_version(x = umap_import$pkg_resources$get_distribution("umap-learn")$version) <
+          numeric_version(x = "0.5.0")) {
+        stop("densmap is only supported by versions >= 0.5.0 of umap-learn. Upgrade umap-learn (e.g. pip install --upgrade umap-learn).")
+      }
+      umap.args <- list(
         n_neighbors = as.integer(x = n.neighbors),
         n_components = as.integer(x = n.components),
         metric = metric,
@@ -1279,6 +1292,17 @@ RunUMAP.default <- function(
         angular_rp_forest = angular.rp.forest,
         verbose = verbose
       )
+      if (numeric_version(x = umap_import$pkg_resources$get_distribution("umap-learn")$version) >=
+          numeric_version(x = "0.5.0")) {
+        umap.args <- c(umap.args, list(
+          densmap = densmap,
+          dens_lambda = dens.lambda,
+          dens_frac = dens.frac,
+          dens_var_shift = dens.var.shift,
+          output_dens = FALSE
+        ))
+      }
+      umap <- do.call(what = umap_import$UMAP, args = umap.args)
       umap$fit_transform(as.matrix(x = object))
     },
     'uwot' = {
@@ -1429,6 +1453,8 @@ RunUMAP.Graph <- function(
   uwot.sgd = FALSE,
   seed.use = 42L,
   metric.kwds = NULL,
+  densmap = FALSE,
+  densmap.kwds = NULL,
   verbose = TRUE,
   reduction.key = 'UMAP_',
   ...
@@ -1484,8 +1510,8 @@ RunUMAP.Graph <- function(
   if (numeric_version(x = umap$pkg_resources$get_distribution("umap-learn")$version) >=
       numeric_version(x = "0.5.0")) {
     umap.args <- c(umap.args, list(
-      densmap = FALSE,
-      densmap_kwds = NULL,
+      densmap = densmap,
+      densmap_kwds = densmap_kwds,
       output_dens = FALSE
     ))
   }
@@ -1590,6 +1616,26 @@ RunUMAP.Neighbor <- function(
 #' approximate nearest neighbor search. This can be faster, but is mostly on useful for metric that
 #' use an angular style distance such as cosine, correlation etc. In the case of those metrics
 #' angular forests will be chosen automatically.
+#' @param densmap Whether to use the density-augmented objective of densMAP.
+#' Turning on this option generates an embedding where the local densities
+#' are encouraged to be correlated with those in the original space.
+#' Parameters below with the prefix ‘dens’ further control the behavior
+#' of this extension. Default is FALSE. Only compatible with 'umap-learn' method
+#' and version of umap-learn >= 0.5.0
+#' @param densmap.kwds A dictionary of arguments to pass on to the densMAP optimization.
+#' @param dens.lambda Specific parameter which controls the regularization weight
+#' of the density correlation term in densMAP. Higher values prioritize density
+#' preservation over the UMAP objective, and vice versa for values closer to zero.
+#' Setting this parameter to zero is equivalent to running the original UMAP algorithm.
+#' Default value is 2.
+#' @param dens.frac Specific parameter which controls the fraction of epochs
+#' (between 0 and 1) where the density-augmented objective is used in densMAP.
+#' The first (1 - dens_frac) fraction of epochs optimize the original UMAP
+#' objective before introducing the density correlation term. Default is 0.3.
+#' @param dens.var.shift Specific parameter which specifies a small constant
+#' added to the variance of local radii in the embedding when calculating
+#' the density correlation objective to prevent numerical instability from
+#' dividing by a small number. Default is 0.1.
 #' @param reduction.name Name to store dimensional reduction under in the Seurat object
 #' @param reduction.key dimensional reduction key, specifies the string before
 #' the number for the dimension names. UMAP by default
@@ -1632,6 +1678,10 @@ RunUMAP.Seurat <- function(
   seed.use = 42L,
   metric.kwds = NULL,
   angular.rp.forest = FALSE,
+  densmap = FALSE,
+  dens.lambda = 2,
+  dens.frac = 0.3,
+  dens.var.shift = 0.1,
   verbose = TRUE,
   reduction.name = 'umap',
   reduction.key = 'UMAP_',
@@ -1714,6 +1764,10 @@ RunUMAP.Seurat <- function(
     seed.use = seed.use,
     metric.kwds = metric.kwds,
     angular.rp.forest = angular.rp.forest,
+    densmap = densmap,
+    dens.lambda = dens.lambda,
+    dens.frac = dens.frac,
+    dens.var.shift = dens.var.shift,
     reduction.key = reduction.key,
     verbose = verbose
   )