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, returning a qshap_result object with better formatting and additional metadata. The qshap_result object includes feature names, total R², sample counts, and provides enhanced print(), summary(), and as.data.frame() methods for easier analysis.

Usage

rsq(
  explainer,
  x,
  y,
  feature_names = NULL,
  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
feature_names	Character vector of feature names. If NULL, uses column names from x.
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)

Details

The local_rsq matrix contains local contributions on the R-squared scale. It decomposes each global feature-specific rsq value across observations and must not be interpreted as an observation-specific coefficient of determination.

This function provides a user-friendly interface for Q-SHAP R² computation:

• Automatically extracts feature names from the input data

• Returns a structured object with metadata

• Provides enhanced printing with top features displayed by default

• Includes a comprehensive summary() method

• Can be easily converted to a data frame with as.data.frame()

Value

A qshap_result object containing:

• rsq: Numeric vector of feature-specific R² values

• feature_names: Character vector of feature names

• total_rsq: Total R² (sum of feature-specific values)

• n_samples: Number of samples

• n_features: Number of features

• loss: Unchanged raw observation-level contributions to the change in squared loss (if local=TRUE)

• local_rsq: Observation-level contributions to the global R-squared decomposition, equal to -loss / Q_emptyset, where Q_\emptyset = \sum_i (y_i - \bar y)^2. Its column sums equal rsq up to numerical tolerance (if local=TRUE)

See Also

qshap_result

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)
result <- rsq(explainer, X, y)
print(result)

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