Merge pull request #170 from ModelOriented/seed-parallel

Add seed and change parallelism

Author: mayer79

DESCRIPTION

@@ -26,12 +26,12 @@ Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.3.2
 Imports: 
+    doFuture,
     foreach,
     MASS,
     stats,
     utils
 Suggests: 
-    doFuture,
     testthat (>= 3.0.0)
 Config/testthat/edition: 3
 URL: https://github.com/ModelOriented/kernelshap

NAMESPACE

@@ -10,4 +10,4 @@ export(additive_shap)
 export(is.kernelshap)
 export(kernelshap)
 export(permshap)
-importFrom(foreach,"%dopar%")
+importFrom(doFuture,"%dofuture%")

NEWS.md

@@ -15,26 +15,33 @@ unit tests against Python's "shap".
 ### API
 
 - The argument `feature_names` can now also be used with matrix input ([#166](https://github.com/ModelOriented/kernelshap/pull/166)).
+- `kernelshap()` and `permshap()` have received a `seed = NULL` argument ([#170](https://github.com/ModelOriented/kernelshap/pull/170)).
+- Parallel mode: If missing packages or globals have to be specified, this now has to be done through `parallel_args = list(packages = ..., globals = ...)` 
+instead of `parallel_args = list(.packages = ..., .globals = ...)`, see section on parallelism below. 
+The list is passed to `[foreach::foreach(.options.future = ...)]`.
 
 ### Speed and memory improvements
 
 - `permshap()` and `kernelshap()` require about 10% less memory ([#166](https://github.com/ModelOriented/kernelshap/pull/166)).
 - `permshap()` and `kernelshap()` are faster for data.frame input, 
   and slightly slower for matrix input ([#166](https://github.com/ModelOriented/kernelshap/pull/166)).
 - Additionally, `permshap(, exact = TRUE)` is faster by pre-calculating more 
-  elements used across rows [#165](https://github.com/ModelOriented/kernelshap/pull/165)
+  elements used across rows ([#165](https://github.com/ModelOriented/kernelshap/pull/165)).
 
-### Documentation
-
-- `kernelshap()` and `permshap()` currently yield a warning on random seed handling in
-  parallel mode, thanks [#163](https://github.com/ModelOriented/kernelshap/issues/163)
-  for reporting. We have added a note in the function documentation that this warning
-  can be ignored.
-  
 ### Internal changes
 
 - Matrices holding on-off vectors are now consistently of type logical ([#167](https://github.com/ModelOriented/kernelshap/pull/167)).
 
+### Changes in parallelism
+
+We have switched from `%dopar%` to `doFuture` ([#170](https://github.com/ModelOriented/kernelshap/pull/170)) with the following impact:
+
+- No need for calling `registerDoFuture()` anymore.
+- Random seeding is properly handled, and respects `seed`, thanks [#163](https://github.com/ModelOriented/kernelshap/issues/163) for reporting.
+- {doFuture} is listed under "imports", not as "suggested".
+- If missing packages or globals have to be specified, this now has to be done through `parallel_args = list(packages = ..., globals = ...)` 
+instead of `parallel_args = list(.packages = ..., .globals = ...)`. The list is passed to `[foreach::foreach(.options.future = ...)]`.
+
 # kernelshap 0.8.0
 
 ### Major improvement

R/kernelshap.R

@@ -54,7 +54,7 @@
 #' should not be higher than 10 for exact calculations.
 #' For similar reasons, degree 2 hybrids should not use \eqn{p} larger than 40.
 #'
-#' @importFrom foreach %dopar%
+#' @importFrom doFuture %dofuture%
 #'
 #' @param object Fitted model object.
 #' @param X \eqn{(n \times p)} matrix or `data.frame` with rows to be explained.
@@ -105,16 +105,18 @@
 #'   For `permshap()`, the default is 0.01, while for `kernelshap()` it is set to 0.005.
 #' @param max_iter If the stopping criterion (see `tol`) is not reached after
 #'   `max_iter` iterations, the algorithm stops. Ignored if `exact = TRUE`.
-#' @param parallel If `TRUE`, use parallel [foreach::foreach()] to loop over rows
-#'   to be explained. Must register backend beforehand, e.g., via 'doFuture' package,
-#'   see README for an example. Parallelization automatically disables the progress bar.
-#' @param parallel_args Named list of arguments passed to [foreach::foreach()].
-#'   Ideally, this is `NULL` (default). Only relevant if `parallel = TRUE`.
+#' @param parallel If `TRUE`, use [foreach::foreach()] and `%dofuture%` to loop over rows
+#'   to be explained. Must register backend beforehand, e.g., `plan(multisession)`,
+#'   see README for an example. Currently disables the progress bar.
+#' @param parallel_args Named list of arguments passed to
+#'   `foreach::foreach(.options.future = ...)`, ideally `NULL` (default).
+#'   Only relevant if `parallel = TRUE`.
 #'   Example on Windows: if `object` is a GAM fitted with package 'mgcv',
-#'   then one might need to set `parallel_args = list(.packages = "mgcv")`.
-#'   The warning "unexpectedly generated random numbers" can be ignored because
-#'   sharing seeds across rows of `X` it is not a problem.
+#'   then one might need to set `parallel_args = list(packages = "mgcv")`.
+#'   Similarly, if the model has been fitted with `ranger()`, then it might be necessary
+#'   to pass `parallel_args = list(packages = "ranger")`.
 #' @param verbose Set to `FALSE` to suppress messages and the progress bar.
+#' @param seed Optional integer random seed. Note that it changes the global seed.
 #' @param survival Should cumulative hazards ("chf", default) or survival
 #'   probabilities ("prob") per time be predicted? Only in `ranger()` survival models.
 #' @param ... Additional arguments passed to `pred_fun(object, X, ...)`.
@@ -195,6 +197,7 @@ kernelshap.default <- function(
     parallel = FALSE,
     parallel_args = NULL,
     verbose = TRUE,
+    seed = NULL,
     ...) {
   p <- length(feature_names)
   basic_checks(X = X, feature_names = feature_names, pred_fun = pred_fun)
@@ -209,6 +212,10 @@ kernelshap.default <- function(
   bg_n <- nrow(bg_X)
   n <- nrow(X)
 
+  if (!is.null(seed)) {
+    set.seed(seed)
+  }
+
   # Calculate v1 and v0
   bg_preds <- align_pred(pred_fun(object, bg_X, ...))
   v0 <- wcolMeans(bg_preds, bg_w) # Average pred of bg data: 1 x K
@@ -254,8 +261,9 @@ kernelshap.default <- function(
 
   # Apply Kernel SHAP to each row of X
   if (isTRUE(parallel)) {
-    parallel_args <- c(list(i = seq_len(n)), parallel_args)
-    res <- do.call(foreach::foreach, parallel_args) %dopar% kernelshap_one(
+    future_args <- c(list(seed = TRUE), parallel_args)
+    parallel_args <- c(list(i = seq_len(n)), list(.options.future = future_args))
+    res <- do.call(foreach::foreach, parallel_args) %dofuture% kernelshap_one(
       x = X[i, , drop = FALSE],
       v1 = v1[i, , drop = FALSE],
       object = object,
@@ -350,6 +358,7 @@ kernelshap.ranger <- function(
     parallel = FALSE,
     parallel_args = NULL,
     verbose = TRUE,
+    seed = NULL,
     survival = c("chf", "prob"),
     ...) {
   if (is.null(pred_fun)) {
@@ -372,6 +381,7 @@ kernelshap.ranger <- function(
     parallel = parallel,
     parallel_args = parallel_args,
     verbose = verbose,
+    seed = seed,
     ...
   )
 }

R/permshap.R

@@ -108,6 +108,7 @@ permshap.default <- function(
     parallel = FALSE,
     parallel_args = NULL,
     verbose = TRUE,
+    seed = NULL,
     ...) {
   p <- length(feature_names)
   if (p <= 1L) {
@@ -132,6 +133,10 @@ permshap.default <- function(
   bg_n <- nrow(bg_X)
   n <- nrow(X)
 
+  if (!is.null(seed)) {
+    set.seed(seed)
+  }
+
   # Baseline and predictions on explanation data
   bg_preds <- align_pred(pred_fun(object, bg_X, ...))
   v0 <- wcolMeans(bg_preds, w = bg_w) # Average pred of bg data: 1 x K
@@ -166,8 +171,9 @@ permshap.default <- function(
 
   # Apply permutation SHAP to each row of X
   if (isTRUE(parallel)) {
-    parallel_args <- c(list(i = seq_len(n)), parallel_args)
-    res <- do.call(foreach::foreach, parallel_args) %dopar% permshap_one(
+    future_args <- c(list(seed = TRUE), parallel_args)
+    parallel_args <- c(list(i = seq_len(n)), list(.options.future = future_args))
+    res <- do.call(foreach::foreach, parallel_args) %dofuture% permshap_one(
       x = X[i, , drop = FALSE],
       v1 = v1[i, , drop = FALSE],
       object = object,
@@ -257,6 +263,7 @@ permshap.ranger <- function(
     parallel = FALSE,
     parallel_args = NULL,
     verbose = TRUE,
+    seed = NULL,
     survival = c("chf", "prob"),
     ...) {
   if (is.null(pred_fun)) {
@@ -278,6 +285,7 @@ permshap.ranger <- function(
     parallel = parallel,
     parallel_args = parallel_args,
     verbose = verbose,
+    seed = seed,
     ...
   )
 }

README.md

@@ -110,15 +110,17 @@ The {kernelshap} package can deal with almost any situation. We will show some o
 
 ### Parallel computing
 
-Parallel computing for `permshap()` and `kernelshap()` is supported via {foreach}. Note that this does not work for all models. 
+Parallel computing for `permshap()` and `kernelshap()` is supported via {doFuture} and {foreach}.
+Note that this does not work for all models. 
 
-On Windows, sometimes not all packages or global objects are passed to the parallel sessions. Often, this can be fixed via `parallel_args`, see this example: 
+On Windows, sometimes not all packages or global objects are passed to the parallel sessions.
+Often, this can be fixed via `parallel_args` using the arguments "packages" and "globals" passed
+to `foreach(.options.future = ...)`, see this example:
 
 ```r
 library(doFuture)
 library(mgcv)
 
-registerDoFuture()
 plan(multisession, workers = 4)  # Windows
 # plan(multicore, workers = 4)   # Linux, macOS, Solaris
 
@@ -127,7 +129,7 @@ fit <- gam(log_price ~ s(log_carat) + clarity * color + cut, data = diamonds)
 
 system.time(  # 4 seconds in parallel
   ps <- permshap(
-    fit, X, bg_X = bg_X, parallel = TRUE, parallel_args = list(.packages = "mgcv")
+    fit, X, bg_X = bg_X, parallel = TRUE, parallel_args = list(packages = "mgcv")
   )
 )
 ps

cran-comments.md

@@ -17,8 +17,7 @@ Thanks a lot!
 
 ### `check_win_devel()`
 
-Status: 1 NOTE
-R Under development (unstable) (2025-07-05 r88387 ucrt)
+Status: OK
 
 ### Revdep OK
 

man/kernelshap.Rd

@@ -37,13 +37,12 @@ use_description(
   roxygen = TRUE
 )
 
+use_package("doFuture", "Imports")
 use_package("foreach", "Imports")
 use_package("MASS", "Imports")
 use_package("stats", "Imports")
 use_package("utils", "Imports")
 
-use_package("doFuture", "Suggests")
-
 use_gpl_license(2)
 
 # Your files that do not belong to the package itself (others are added by "use_* function")