NorskRegnesentral/shapr v1.1.0

shapr 1.1.0

on GitHub

New features

• Added the "arf" approach for conditional sampling with adversarial random forests via the arf package (#497)
• Added the extra_computation_args$max_batch_cube_size argument, which caps the dense per-batch array of the gaussian, copula and empirical approaches by automatically using more batches in high-dimensional settings, avoiding the RcppArmadillo Cube::init(): requested size is too large failure and often reducing runtime. For gaussian/copula the array has n_MC_samples * n_explain * coalitions_per_batch * n_features elements, and for empirical it is the distance array with n_train * n_explain * coalitions_per_batch elements. Defaults to 1e6 elements. (#504)
• The basic verbose output now reports how many batches the coalitions are split into and the mean number of coalitions per batch. (#504, #517)
• Added support for SAGE (Shapley Additive Global importancE) values via the new scope and y_explain arguments to explain(). Set scope = "global" to explain the model's global loss (using extra_computation_args$global_loss_func, defaulting to log-loss for binary 0/1 responses and MSE otherwise) instead of individual predictions, and plot the result with plot() using plot_type = "bar" or "waterfall". scope = "global" also works together with grouping (group), causal Shapley values (causal_ordering/confounding), and asymmetric Shapley values (asymmetric). (#503)
• explain() now errors early when the vaeac approach uses future batching with a serializing parallelization backend (a future multisession or cluster plan) with more than one worker, since torch objects are external pointers that cannot be exported to separate R processes. Use a forking plan (future::plan(future::multicore)) or set extra_computation_args$vS_batching_method = "forloop". (#507, #517)

Bug fixes

• Avoided extra blank lines in knitted informational output by using CLI display messages consistently, while preserving preformatted tables and message suppression. (#519)
• Fixed a bug in the vaeac approach where an all-categorical data set whose features all have the same number of levels was encoded incorrectly, causing a torch index ... is out of bounds error. vaeac_preprocess_data() used sapply(data, levels), which simplifies to a matrix (instead of a per-feature list) when every feature is a factor with the same number of levels, corrupting one_hot_max_sizes. (#506)
• Fixed a bug where non-iterative estimation (iterative = FALSE) with a moderate number of features could ignore max_n_coalitions and enumerate all 2^n_features coalitions (an incorrect exact-computation threshold of n_shapley_values^2 instead of 2^n_shapley_values), causing severe slowdowns and RcppArmadillo Cube::init() failures in high dimensions. (#505)
• Fixed handling of ordered factor features by treating them as factors in feature specifications and adding stricter checks for malformed feature specification lists. (#495)
• Fixed cli::cli_progress_step() reporting artificially short timings for the v(S) computation step by passing .envir = parent.frame() to bind the progress bar's lifetime to the correct calling environment. (#496)

Development and testing

• Added repository-wide agent instructions, VS Code tasks, and snapshot-safe local testing helpers (#493).
• Added pre-PR workflow scripts (dev/prepare-pr, dev/check-pr, dev/publish-pr) with dev/pr-workflow.md for automated and agent-assisted PR readiness checks; consolidated development scripts under dev/. (#494)
• Added a full computational benchmark suite for runtime and peak RAM usage across the supported approaches and representative workloads, together with a pkgdown article presenting the retained results. The benchmark framework includes coalition-budget validation for iterative pairs, corrected process-tree RAM polling, and optional realistic parallel-workload studies. (#510, #517, #520)
• Skip vdiffr plot snapshot tests on R < 4.5.0 to avoid spurious failures caused by formatting changes in older R versions. (#494)
• Added macOS-only smoke tests for the "arf" and "vaeac" approaches that verify explain() runs without errors and that the returned Shapley values satisfy the efficiency property, providing platform coverage for the snapshot tests skipped on macOS. (#497)
• Added scheduled/manual maintenance runs for R CMD check and Python tests, and updated Python testing to use uv with Python 3.14 (#493).

Documentation

• Simplified roxygen2 (following package update) inheritance for approach-specific arguments and refreshed affected documentation (#493).
• Updated computational benchmark reporting to use wall time measured directly around explain() rather than fresh-process runtime, while retaining harness timings as diagnostics, and refreshed the retained results so all published peak RAM values use cgroup-v2 memory.peak. (#511)
• Added practical guidance in README and general usage vignette for choosing conditional approaches, covering computational cost, the MSEv evaluation criterion, and recommendations from Olsen et al. (2024). (#513)

Python

• Renamed the Python wrapper from shaprpy to pyshapr. R console output from summary()/print() on Python-initiated explanations now references pyshapr.explain()/pyshapr.explain_forecast(). A thin shaprpy compatibility package remains available on PyPI for a transition period. (#500)