Merge pull request #211 from satijalab/develop

v0.4.3

Author: saketkc

DESCRIPTION

@@ -1,8 +1,8 @@
 Package: sctransform
 Type: Package
 Title: Variance Stabilizing Transformations for Single Cell UMI Data
-Version: 0.4.2
-Date: 2025-04-30
+Version: 0.4.3
+Date: 2025-12-25
 Authors@R: c(
   person(given = "Christoph", family = "Hafemeister", email = "christoph.hafemeister@nyu.edu", role = "aut", comment = c(ORCID = "0000-0001-6365-8254")),
   person(given = "Saket", family = "Choudhary", email = "saketc@iitb.ac.in", role = c("aut", "cre"), comment = c(ORCID = "0000-0001-5202-7633")),
@@ -31,6 +31,7 @@ Imports:
   methods,
   future.apply,
   future,
+  parallelly,
   ggplot2,
   reshape2,
   rlang,
@@ -42,4 +43,4 @@ Suggests:
   knitr
 Enhances:
   glmGamPoi
-RoxygenNote: 7.3.2
+RoxygenNote: 7.3.3

NEWS.md

@@ -1,6 +1,13 @@
 # News
 All notable changes will be documented in this file.
 
+## [0.4.3] - 2025-12-25
+
+- Fixed imports for supportsMulticore() to use parallely [#209](https://github.com/satijalab/sctransform/issues/209)
+- Switch to future_apply [#210](https://github.com/satijalab/sctransform/issues/210)
+- Remove deprecated argument 'verbose' in favor of 'verbosity'
+- Added helper functions for progress bar and parsing formulas
+
 ## [0.4.2] - 2025-04-30
 
 ### Fixed
@@ -41,7 +48,7 @@ All notable changes will be documented in this file.
 ## [0.3.4] - 2022-08-19
 
 ### Added
-- Add `make.sparse` to handle `dgCMatrix` coercsions 
+- Add `make.sparse` to handle `dgCMatrix` coercions 
 
 ### Fixed
 - Convert bitwise operators to boolean operators in utils.cpp

R/data.R

@@ -6,7 +6,7 @@
 #' There are 914 rows (genes) and 283 columns (cells). This is a downsampled
 #' version of a 3K PBMC dataset available from 10x Genomics.
 #'
-#' @source \url{https://support.10xgenomics.com/single-cell-gene-expression/datasets/1.1.0/pbmc3k}
+#' @source \url{https://www.10xgenomics.com/datasets/3-k-pbm-cs-from-a-healthy-donor-1-standard-1-1-0}
 "pbmc"
 
 #' Transformation functions for umify

R/denoise.R

@@ -66,9 +66,7 @@ smooth_via_pca <- function(x, elbow_th = 0.025, dims_use = NULL, max_pc = 100, d
 #' @param do_pos Set negative values in the result to zero
 #' @param scale_factor Replace all values of UMI in the regression model by this value. Default is NA
 #' which uses median of total UMI as the latent factor.
-#' @param verbosity An integer specifying whether to show only messages (1), messages and progress bars (2) or nothing (0) while the function is running; default is 2
-#' @param verbose Deprecated; use verbosity instead
-#' @param show_progress Deprecated; use verbosity instead
+#' @param verbosity An integer specifying the verbosity level: 0 (silent, no messages), 1 (show messages only), or 2 (show messages and progress bars); default is 2
 #'
 #' @return Corrected data as UMI counts
 #'
@@ -81,22 +79,7 @@ smooth_via_pca <- function(x, elbow_th = 0.025, dims_use = NULL, max_pc = 100, d
 #' }
 #'
 correct <- function(x, data = 'y', cell_attr = x$cell_attr, as_is = FALSE,
-                    do_round = TRUE, do_pos = TRUE, scale_factor=NA, verbosity = 2,
-                    verbose = NULL, show_progress = NULL) {
-  # Take care of deprecated arguments
-  if (!is.null(verbose)) {
-    warning("The 'verbose' argument is deprecated as of v0.3. Use 'verbosity' instead. (in sctransform::vst)", immediate. = TRUE, call. = FALSE)
-    verbosity <- as.numeric(verbose)
-  }
-  if (!is.null(show_progress)) {
-    warning("The 'show_progress' argument is deprecated as of v0.3. Use 'verbosity' instead. (in sctransform::vst)", immediate. = TRUE, call. = FALSE)
-    if (show_progress) {
-      verbosity <- 2
-    } else {
-      verbosity <- min(verbosity, 1)
-    }
-  }
-
+                    do_round = TRUE, do_pos = TRUE, scale_factor=NA, verbosity = 2) {
   if (is.character(data)) {
     data <- x[[data]]
   }
@@ -121,18 +104,17 @@ correct <- function(x, data = 'y', cell_attr = x$cell_attr, as_is = FALSE,
     }
     cell_attr[, "log_umi"] <- log10(scale_factor)
   }
-  regressor_data <- model.matrix(as.formula(gsub('^y', '', x$model_str)), cell_attr)
+  regressor_data <- model.matrix(get_model_formula(x$model_str), cell_attr)
 
   genes <- rownames(data)
   bin_size <- x$arguments$bin_size
-  bin_ind <- ceiling(x = 1:length(x = genes) / bin_size)
-  max_bin <- max(bin_ind)
   if (verbosity > 0) {
     message('Computing corrected count matrix for ', length(genes), ' genes')
   }
-  if (verbosity > 1) {
-    pb <- txtProgressBar(min = 0, max = max_bin, style = 3)
-  }
+  pb_setup <- setup_progress_bar(length(genes), bin_size, verbosity)
+  bin_ind <- pb_setup$bin_ind
+  max_bin <- pb_setup$max_bin
+  pb <- pb_setup$pb
   corrected_data <- matrix(NA_real_, length(genes), nrow(regressor_data), dimnames = list(genes, rownames(regressor_data)))
   for (i in 1:max_bin) {
     genes_bin <- genes[bin_ind == i]
@@ -142,13 +124,9 @@ correct <- function(x, data = 'y', cell_attr = x$cell_attr, as_is = FALSE,
     mu <- exp(tcrossprod(coefs, regressor_data))
     variance <- mu + mu^2 / theta
     corrected_data[genes_bin, ] <- mu + pearson_residual * sqrt(variance)
-    if (verbosity > 1) {
-      setTxtProgressBar(pb, i)
-    }
-  }
-  if (verbosity > 1) {
-    close(pb)
+    update_progress_bar(pb, i, verbosity)
   }
+  close_progress_bar(pb, verbosity)
 
   if (do_round) {
     corrected_data <- round(corrected_data, 0)
@@ -170,9 +148,7 @@ correct <- function(x, data = 'y', cell_attr = x$cell_attr, as_is = FALSE,
 #' @param cell_attr Provide cell meta data holding latent data info
 #' @param scale_factor Replace all values of UMI in the regression model by this value. Default is NA
 #' which uses median of total UMI as the latent factor.
-#' @param verbosity An integer specifying whether to show only messages (1), messages and progress bars (2) or nothing (0) while the function is running; default is 2
-#' @param verbose Deprecated; use verbosity instead
-#' @param show_progress Deprecated; use verbosity instead
+#' @param verbosity An integer specifying the verbosity level: 0 (silent, no messages), 1 (show messages only), or 2 (show messages and progress bars); default is 2
 #'
 #' @return Corrected data as UMI counts
 #'
@@ -186,23 +162,8 @@ correct <- function(x, data = 'y', cell_attr = x$cell_attr, as_is = FALSE,
 #' umi_corrected <- correct_counts(vst_out, pbmc)
 #' }
 #'
-correct_counts <- function(x, umi, cell_attr = x$cell_attr, scale_factor = NA, verbosity = 2,
-                           verbose = NULL, show_progress = NULL) {
-  # Take care of deprecated arguments
-  if (!is.null(verbose)) {
-    warning("The 'verbose' argument is deprecated as of v0.3. Use 'verbosity' instead. (in sctransform::vst)", immediate. = TRUE, call. = FALSE)
-    verbosity <- as.numeric(verbose)
-  }
-  if (!is.null(show_progress)) {
-    warning("The 'show_progress' argument is deprecated as of v0.3. Use 'verbosity' instead. (in sctransform::vst)", immediate. = TRUE, call. = FALSE)
-    if (show_progress) {
-      verbosity <- 2
-    } else {
-      verbosity <- min(verbosity, 1)
-    }
-  }
-
-  regressor_data_orig <- model.matrix(as.formula(gsub('^y', '', x$model_str)), cell_attr)
+correct_counts <- function(x, umi, cell_attr = x$cell_attr, scale_factor = NA, verbosity = 2) {
+  regressor_data_orig <- model.matrix(get_model_formula(x$model_str), cell_attr)
   # when correcting, set all latent variables to median values
   cell_attr[, x$arguments$latent_var] <- apply(cell_attr[, x$arguments$latent_var, drop=FALSE], 2, function(x) rep(median(x), length(x)))
 
@@ -215,18 +176,17 @@ correct_counts <- function(x, umi, cell_attr = x$cell_attr, scale_factor = NA, v
     }
     cell_attr[, "log_umi"] <- log10(scale_factor)
   }
-  regressor_data <- model.matrix(as.formula(gsub('^y', '', x$model_str)), cell_attr)
+  regressor_data <- model.matrix(get_model_formula(x$model_str), cell_attr)
 
   genes <- rownames(umi)[rownames(umi) %in% rownames(x$model_pars_fit)]
   bin_size <- x$arguments$bin_size
-  bin_ind <- ceiling(x = 1:length(x = genes) / bin_size)
-  max_bin <- max(bin_ind)
   if (verbosity > 0) {
     message('Computing corrected UMI count matrix')
   }
-  if (verbosity > 1) {
-    pb <- txtProgressBar(min = 0, max = max_bin, style = 3)
-  }
+  pb_setup <- setup_progress_bar(length(genes), bin_size, verbosity)
+  bin_ind <- pb_setup$bin_ind
+  max_bin <- pb_setup$max_bin
+  pb <- pb_setup$pb
   #corrected_data <- matrix(NA_real_, length(genes), nrow(regressor_data), dimnames = list(genes, rownames(regressor_data)))
   corrected_data <- list()
   for (i in 1:max_bin) {
@@ -245,13 +205,9 @@ correct_counts <- function(x, umi, cell_attr = x$cell_attr, scale_factor = NA, v
     y.res <- round(y.res, 0)
     y.res[y.res < 0] <- 0
     corrected_data[[length(corrected_data) + 1]] <- make.sparse(mat = y.res)
-    if (verbosity > 1) {
-      setTxtProgressBar(pb, i)
-    }
-  }
-  if (verbosity > 1) {
-    close(pb)
+    update_progress_bar(pb, i, verbosity)
   }
+  close_progress_bar(pb, verbosity)
   corrected_data <- do.call(what = rbind, args = corrected_data)
 
   return(corrected_data)

R/differential_expression.R

@@ -8,13 +8,11 @@
 #' @param method Either 'LRT' for likelihood ratio test, or 't_test' for t-test
 #' @param bin_size Number of genes that are processed between updates of progress bar
 #' @param cell_attr Data frame of cell meta data
-#' @param y Only used if methtod = 't_test', this is the residual matrix; default is x$y
+#' @param y Only used if method = 't_test', this is the residual matrix; default is x$y
 #' @param min_cells A gene has to be detected in at least this many cells in at least one of the groups being compared to be tested
 #' @param weighted Balance the groups by using the appropriate weights
 #' @param randomize Boolean indicating whether to shuffle group labels - only set to TRUE when testing methods
-#' @param verbosity An integer specifying whether to show only messages (1), messages and progress bars (2) or nothing (0) while the function is running; default is 2
-#' @param verbose Deprecated; use verbosity instead
-#' @param show_progress Deprecated; use verbosity instead
+#' @param verbosity An integer specifying the verbosity level: 0 (silent, no messages), 1 (show messages only), or 2 (show messages and progress bars); default is 2
 #'
 #' @return Data frame of results
 #'
@@ -25,27 +23,7 @@
 #'
 compare_expression <- function(x, umi, group, val1, val2, method = 'LRT', bin_size = 256,
                                cell_attr = x$cell_attr, y = x$y, min_cells = 5,
-                               weighted = TRUE, randomize = FALSE, verbosity = 2,
-                               verbose = NULL, show_progress = NULL) {
-  if (nbrOfWorkers() == 1){
-    my.lapply <- function(X, FUN, future.seed = TRUE) lapply(X, FUN)
-  } else {
-    my.lapply <- future_lapply
-  }
-  # Take care of deprecated arguments
-  if (!is.null(verbose)) {
-    warning("The 'verbose' argument is deprecated as of v0.3. Use 'verbosity' instead. (in sctransform::vst)", immediate. = TRUE, call. = FALSE)
-    verbosity <- as.numeric(verbose)
-  }
-  if (!is.null(show_progress)) {
-    warning("The 'show_progress' argument is deprecated as of v0.3. Use 'verbosity' instead. (in sctransform::vst)", immediate. = TRUE, call. = FALSE)
-    if (show_progress) {
-      verbosity <- 2
-    } else {
-      verbosity <- min(verbosity, 1)
-    }
-  }
-
+                               weighted = TRUE, randomize = FALSE, verbosity = 2) {
   if (! method %in% c('LRT', 'LRT_free', 'LRT_reg', 't_test')) {
     stop('method needs to be either \'LRT\', \'LRT_free\', \'LRT_reg\' or \'t_test\'')
   }
@@ -99,16 +77,16 @@ compare_expression <- function(x, umi, group, val1, val2, method = 'LRT', bin_si
   for (i in 1:max_bin) {
     genes_bin <- genes[bin_ind == i]
     if (method == 't_test') {
-      bin_res <- my.lapply(
-        X = genes_bin, 
+      bin_res <- future_lapply(
+        X = genes_bin,
         FUN = function(gene) {model_comparison_ttest(y[gene, use_cells], group)},
         future.seed = TRUE)
     }
     if (method == 'LRT') {
       mu <- x$model_pars_fit[genes_bin, -1, drop=FALSE] %*% t(regressor_data)  # in log space
       y <- as.matrix(umi[genes_bin, use_cells])
-      bin_res <- my.lapply(
-        X = genes_bin, 
+      bin_res <- future_lapply(
+        X = genes_bin,
         FUN = function(gene) {
           model_comparison_lrt(y[gene, ], mu[gene, ], x$model_pars_fit[gene, 'theta'], group, weights)},
         future.seed = TRUE)
@@ -181,11 +159,11 @@ compare_expression <- function(x, umi, group, val1, val2, method = 'LRT', bin_si
       y_theta[o] <- 10 ^ ksmooth(x = x$genes_log_mean_step1, y = log10(x$model_pars[, 'theta']),
                                  x.points = y_log_mean, bandwidth = bw, kernel='normal')$y
       names(y_theta) <- genes_bin
-      bin_res <- my.lapply(
-        X = genes_bin, 
+      bin_res <- future_lapply(
+        X = genes_bin,
         FUN = function(gene) {
           return(model_comparison_lrt_free3(gene, y[gene, ], y_theta[gene], x$model_str, cell_attr, group, weights, randomize))
-        }, 
+        },
         future.seed = TRUE)
     }
     res[[i]] <- do.call(rbind, bin_res)

R/plotting.R

@@ -4,9 +4,7 @@
 #' @param xaxis Variable to plot on X axis; default is "gmean"
 #' @param show_theta Whether to show the theta parameter; default is FALSE (only the overdispersion factor is shown)
 #' @param show_var Whether to show the average model variance; default is FALSE
-#' @param verbosity An integer specifying whether to show only messages (1), messages and progress bars (2) or nothing (0) while the function is running; default is 2
-#' @param verbose Deprecated; use verbosity instead
-#' @param show_progress Deprecated; use verbosity instead
+#' @param verbosity An integer specifying the verbosity level: 0 (silent, no messages), 1 (show messages only), or 2 (show messages and progress bars); default is 2
 #'
 #' @return A ggplot object
 #'
@@ -22,21 +20,7 @@
 #' }
 #'
 plot_model_pars <- function(vst_out, xaxis="gmean", show_theta = FALSE, show_var = FALSE,
-                            verbosity = 2, verbose = NULL, show_progress = NULL) {
-  # Take care of deprecated arguments
-  if (!is.null(verbose)) {
-    warning("The 'verbose' argument is deprecated as of v0.3. Use 'verbosity' instead. (in sctransform::vst)", immediate. = TRUE, call. = FALSE)
-    verbosity <- as.numeric(verbose)
-  }
-  if (!is.null(show_progress)) {
-    warning("The 'show_progress' argument is deprecated as of v0.3. Use 'verbosity' instead. (in sctransform::vst)", immediate. = TRUE, call. = FALSE)
-    if (show_progress) {
-      verbosity <- 2
-    } else {
-      verbosity <- min(verbosity, 1)
-    }
-  }
-
+                            verbosity = 2) {
   if (! 'gmean' %in% names(vst_out$gene_attr)) {
     stop('vst_out must contain a data frame named gene_attr with a column named gmean (perhaps call vst with return_gene_attr = TRUE)')
   }