qshap_rsq: Calculate Feature-Specific R-Squared Values

In qshap: Fast Calculation of Feature Contributions in Boosting Trees

Calculate Feature-Specific R-Squared Values

Description

Computes feature-specific R-squared values using Q-SHAP decomposition. Supports parallel processing and sampling for large datasets.

Usage

qshap_rsq(
  explainer,
  x,
  y,
  local = FALSE,
  nsample = NULL,
  sd_out = TRUE,
  nfrac = NULL,
  random_state = 42,
  ncore = 1L
)

Arguments

explainer	A qshap_tree_explainer object created by gazer()
x	Feature matrix or data frame with n samples and p features
y	Response vector of length n
local	Logical; if TRUE, also returns the raw observation-level squared-loss contributions in loss and their normalized contributions to the global R-squared decomposition in local_rsq.
nsample	Optional integer; number of samples to use (random subsample if less than nrow(x))
sd_out	Logical; if TRUE, returns standard deviations of R-squared estimates
nfrac	Optional numeric in (0,1); fraction of samples to use (alternative to nsample)
random_state	Integer seed for reproducible sampling
ncore	Number of cores for parallel processing. Use -1 for all available cores, or a positive integer. Default is 1 (no parallelization)

Value

A qshap_rsq object containing the feature-specific R-squared vector in rsq and, when requested, sd_rsq. If local=TRUE, the object also contains loss and local_rsq. The loss matrix is the unchanged raw observation-level Shapley decomposition of the change in squared loss. If Q_\emptyset = \sum_i (y_i - \bar y)^2, then local_rsq = -loss / Q_emptyset. Thus, local_rsq contains observation-level contributions to the global R-squared decomposition; it is not an observation-specific coefficient of determination.

Examples

library(xgboost)
set.seed(42)
n <- 100
p <- 100
X <- matrix(rnorm(n * p), nrow = n, ncol = p)
y <- X[, 1] - X[, 2] + rnorm(n, sd = 0.2)
model <- xgboost(X, y, nrounds = 15, max_depth = 2, verbosity = 0, nthread = 1)
explainer <- gazer(model)
phi_rsq <- qshap(explainer, X, y)
print(phi_rsq)

qshap documentation built on Aug. 23, 2026, 5:11 p.m.