Package {qshap}


Type: Package
Title: Fast Calculation of Feature Contributions in Boosting Trees
Version: 3.0.0
Date: 2026-11-19
Description: Computes feature-specific R-squared (R2) contributions for boosting tree models using a Shapley-value-based decomposition of the total R-squared in polynomial time. Supports models fitted with 'XGBoost', 'LightGBM', and 'CatBoost', with optimized backend-specific implementations and cached tree summaries suitable for large-scale problems. Multiple visualization tools are included for interpreting and communicating feature contributions. The methodology is described in Jiang, Zhang, and Zhang (2025) <doi:10.48550/arXiv.2407.03515>. Optional 'CatBoost' support uses the R package 'catboost', which is not distributed on CRAN; installation instructions and released binaries are provided by the CatBoost project at https://catboost.ai/docs/en/concepts/r-installation.
License: GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
URL: https://github.com/catstats/Q-SHAP_R
BugReports: https://github.com/catstats/Q-SHAP_R/issues
Imports: Rcpp (≥ 1.0.14), xgboost (≥ 3.1.3.1), parallel, lightgbm, viridisLite, ggplot2, scales, jsonlite, methods, progress
Suggests: shiny
LinkingTo: Rcpp, RcppEigen
Config/roxygen2/version: 8.1.0
Encoding: UTF-8
NeedsCompilation: yes
Packaged: 2026-11-18 18:22:12 UTC; runneradmin
Author: Steven He [aut], Zhongli Jiang [aut, cre], Dabao Zhang [aut]
Maintainer: Zhongli Jiang <zhongli.jiang.stats@gmail.com>
Repository: CRAN
Date/Publication: 2026-11-19 03:20:02 UTC

Calculating Feature-Specific R-Squared Values for Boosting Trees

Description

The qshap package computes feature-specific R-squared values using Shapley decomposition of the total R-squared for boosting trees built in xgboost and lightgbm. It supports parallel computing.

Details

The package provides fast computation of feature importance through Shapley values for tree ensemble models. Main functions include:

The method uses polynomial-time complexity for Shapley value calculation and includes built-in support for multi-core processing.

Author(s)

Steven He, Zhongli Jiang, Min Zhang, Dabao Zhang

References

Zhongli Jiang, Min Zhang, and Dabao Zhang. 2025. Fast calculation of feature contributions in boosting trees. In Proceedings of the Forty-First Conference on Uncertainty in Artificial Intelligence (UAI '25), Vol. 286. JMLR.org, Article 82, 1859–1875.

See Also

Useful links:

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


Coercion method to data.frame for qshap_result

Description

Coercion method to data.frame for qshap_result

Usage

## S3 method for class 'qshap_result'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

x

A qshap_result object

row.names

Not used

optional

Not used

...

Additional arguments (currently unused)

Value

A data.frame with columns feature (character) and rsq (numeric), sorted by rsq in decreasing order.


Create a QSHAP Tree Explainer

Description

Creates an explainer object for computing feature-specific Shapley values from a trained tree ensemble model. Supports XGBoost, LightGBM, and CatBoost models.

Usage

gazer(model, max_depth = NULL, base_score = NULL, ...)

Arguments

model

A model object of class xgboost or xgb.Booster from xgboost, class lgb.Booster from lightgbm, or class catboost.Model from catboost

max_depth

Maximum depth of trees, extracted from model by default.

base_score

Base score for predictions, extracted from model by default.

...

Additional arguments, for future use

Value

A qshap_tree_explainer containing the model information and preprocessed tree structures. All supported backends share this class; the model_type field records the backend for internal dispatch.

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)


Return a Tree Stored by Gazer

Description

Return a Tree Stored by Gazer

Usage

get_tree(explainer, tree = 1L)

## Default S3 method:
get_tree(explainer, tree = 1L)

## S3 method for class 'qshap_tree_explainer'
get_tree(explainer, tree = 1L)

Arguments

explainer

A Q-SHAP explainer created by gazer().

tree

One-based index of the tree to return.

Details

The generic rejects unsupported explainer classes. The method for qshap_tree_explainer validates the stored tree list and requires a finite, scalar, one-based integer index within that list.

Value

The stored simple_tree object, containing the low-level tree fields and retaining its tree class and print method.


Extract Local Contributions to the Global R-squared Decomposition

Description

Extract Local Contributions to the Global R-squared Decomposition

Usage

local_rsq(x, ...)

## Default S3 method:
local_rsq(x, ...)

## S3 method for class 'qshap_result'
local_rsq(x, ...)

Arguments

x

A result returned by rsq(..., local = TRUE).

...

Additional arguments (currently unused).

Details

The accessor reports an error when local contributions were not requested, or when the stored matrix or feature labels are inconsistent. The input result is not modified.

Value

A numeric matrix with observations in rows and features in columns. Feature labels are taken from the result metadata when available. Column sums reproduce its global feature contributions. These entries are contributions to the global decomposition, not individual R-squared values.

Examples

contributions <- matrix(c(0.1, 0.2, -0.05, 0.15), nrow = 2)
result <- qshap_result(colSums(contributions),
                       feature_names = c("a", "b"), n_samples = 2,
                       local_rsq = contributions)
local_rsq(result)

Alias for qshap_loss

Description

This is a convenience alias for qshap_loss() that provides a shorter function name for calculating feature-specific loss contributions.

Usage

loss(explainer, x, y, y_mean_ori = NULL)

Arguments

explainer

A qshap_tree_explainer object created by gazer()

x

Feature matrix or data frame

y

Response vector

y_mean_ori

Optional pre-computed mean of y (for efficiency)

Value

A matrix of loss contributions with dimensions (n_samples, n_features)

See Also

qshap_loss

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)
loss_matrix <- loss(explainer, X, y)
dim(loss_matrix)


Constructor for qshap_result class

Description

Creates a qshap_result object to store Q-SHAP R-squared results

Usage

new_qshap_result(
  rsq,
  feature_names = NULL,
  total_rsq = NULL,
  n_samples = NULL,
  n_features = NULL,
  loss = NULL,
  local_rsq = NULL
)

Arguments

rsq

Numeric vector of feature-specific R-squared values

feature_names

Character vector of feature names (optional)

total_rsq

Numeric total R-squared (sum of feature-specific values)

n_samples

Integer number of samples used

n_features

Integer number of features

loss

Optional raw observation-level squared-loss contribution matrix (n_samples x n_features).

local_rsq

Optional matrix of observation-level contributions to the global R-squared decomposition (n_samples x n_features). Its column sums equal the feature-specific values in rsq.

Value

An object of class qshap_result


Constructor for qshap_tree_explainer class

Description

Creates a qshap_tree_explainer object

Usage

new_qshap_tree_explainer(
  model,
  model_type,
  max_depth,
  base_score = NULL,
  trees,
  store_v_invc,
  store_z
)

Arguments

model

The original tree model object

model_type

Character string indicating the model backend: "xgboost", "lightgbm", or "catboost".

max_depth

Integer maximum tree depth

base_score

Numeric base score (for XGBoost)

trees

List of tree objects

store_v_invc

Precomputed complex values for SHAP computation

store_z

Precomputed root values for SHAP computation

Value

An object of class qshap_tree_explainer


Constructor for simple_tree class

Description

Creates a simple_tree object with validation

Usage

new_simple_tree(
  children_left,
  children_right,
  feature,
  threshold,
  max_depth,
  n_node_samples,
  value,
  node_count,
  default_left = NULL,
  xgboost_split = FALSE
)

Arguments

children_left

Integer vector of left child indices (-1 for leaf nodes)

children_right

Integer vector of right child indices (-1 for leaf nodes)

feature

Integer vector of feature indices used for splitting (-1 for leaf nodes)

threshold

Numeric vector of threshold values for splits

max_depth

Integer maximum depth of the tree

n_node_samples

Numeric vector of node covers or weights, such as sample counts or summed Hessians

value

Numeric vector of node values

node_count

Integer total number of nodes in the tree

default_left

Logical vector indicating the missing-value direction.

xgboost_split

Logical; use XGBoost float32 strict-less routing.

Value

An object of class simple_tree


Constructor for tree_summary class

Description

Creates a tree_summary object with validation

Usage

new_tree_summary(
  children_left,
  children_right,
  feature,
  feature_uniq,
  threshold,
  max_depth,
  sample_weight,
  init_prediction,
  node_count,
  default_left = NULL,
  xgboost_split = FALSE
)

Arguments

children_left

Integer vector of left child indices

children_right

Integer vector of right child indices

feature

Integer vector of feature indices

feature_uniq

Integer vector of unique feature indices used in tree

threshold

Numeric vector of threshold values

max_depth

Integer maximum depth

sample_weight

Numeric vector of sample weights per node

init_prediction

Numeric vector of initial predictions per node

node_count

Integer total number of nodes

default_left

Logical vector indicating the missing-value direction.

xgboost_split

Logical; use XGBoost float32 strict-less routing.

Value

An object of class tree_summary


Plot method for qshap_result objects

Description

This S3 method enables 'plot(x, ...)' where 'x' is a 'qshap_result' object. It dispatches to the visualization functions in 'vis'.

Usage

## S3 method for class 'qshap_result'
plot(
  x,
  y = NULL,
  type = c("rsq", "elbow", "cumu", "gcorr", "hist", "density", "loss", "heatmap",
    "loss_heatmap"),
  ...
)

Arguments

x

A 'qshap_result' object.

y

Not used.

type

Plot type: one of "rsq", "elbow", "cumu", "gcorr", "hist", "density", "loss", or "heatmap". '"loss_heatmap"' is retained as an alias for '"heatmap"'.

...

Passed to the underlying visualization function.

Value

A ggplot2 object (invisibly).


Plot observation-level contributions

Description

Draws an efficient raster heatmap for selected observations, with a narrow total-contribution strip. For a local Q-SHAP result, the default display is 'local_rsq': observation-level contributions to the global R-squared decomposition, with legend values formatted as percentages. The underlying values remain unchanged. The diverging fill scale is centered at zero.

Usage

plot_loss_heatmap(
  loss,
  global_importance = NULL,
  feature_names = NULL,
  quantity = NULL,
  samples = NULL,
  n_show = 40,
  title = NULL,
  xtitle = "Feature",
  ytitle = "Observations",
  legend_title = NULL,
  low_color = "#2166AC",
  mid_color = "white",
  high_color = "#B2182B",
  rotation = 45,
  save_name = NULL
)

Arguments

loss

A numeric contribution matrix with observations in rows and features in columns, or a 'qshap_result' object produced with 'local = TRUE'.

global_importance

Optional numeric vector used to order features from most to least globally important. For a 'qshap_result' object, '$rsq' is used automatically. For a matrix, the default is '-colSums(loss)' when 'quantity = "loss"' and 'colSums(loss)' when 'quantity = "local_rsq"'.

feature_names

Optional feature labels. Defaults to 'colnames(loss)'.

quantity

Quantity to display when 'loss' is a Q-SHAP result: '"local_rsq"' for local contributions on the R-squared scale or '"loss"' for raw contributions to the change in squared loss. The default uses 'local_rsq' when available and otherwise falls back to 'loss'. For a matrix, this argument controls labels and the default feature-ordering rule; the matrix itself is displayed unchanged.

samples

Optional observation indices or row names/IDs to display. If 'NULL', informative observations are selected automatically from both extremes of the row sums.

n_show

Total number of observations selected automatically when 'samples = NULL'. Approximately half are taken from each extreme.

title

Optional plot title. For 'local_rsq', the default is "Observation-level contributions to the global R^2 decomposition".

xtitle

X-axis title.

ytitle

Y-axis title.

legend_title

Optional fill legend title. Defaults to "Local R^2 contribution" for 'local_rsq'.

low_color

Color for negative contributions.

mid_color

Color for zero.

high_color

Color for positive contributions.

rotation

Rotation angle for feature labels.

save_name

Optional output path without the '.pdf' extension.

Value

A ggplot2 object, invisibly.


Plot Q-SHAP R-squared contributions

Description

Convenience wrapper that works for both a 'qshap_result' object and a plain numeric vector of contributions. Use this if you have a numeric vector and still want to pass arguments like 'color_map_name'.

Usage

plot_qshap(
  x,
  type = c("rsq", "elbow", "cumu", "gcorr", "hist", "density", "loss", "heatmap",
    "loss_heatmap"),
  ...
)

Arguments

x

A 'qshap_result' object (recommended) or a numeric vector.

type

Plot type; see 'plot.qshap_result'. Use '"loss"' to launch the interactive explorer or '"heatmap"' for the static raster heatmap.

...

Additional arguments passed to the underlying visualization function (e.g., 'label', 'rotation', 'color_map_name', 'max_feature').

Value

The ggplot2 plot object (invisibly)

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 = 15L, max_depth = 2L, verbosity = 0L, nthreads = 1L)
explainer <- gazer(model)
phi_rsq <- rsq(explainer, X, y)
plot(phi_rsq)


Print method for qshap_result

Description

Print method for qshap_result

Usage

## S3 method for class 'qshap_result'
print(x, n = 10, ...)

Arguments

x

A qshap_result object

n

Integer number of top features to display (default: 10)

...

Additional arguments (currently unused)

Value

The input x is returned invisibly. Called primarily for its side effect of printing a summary of the qshap_result object to the console.


Print method for qshap_tree_explainer

Description

Print method for qshap_tree_explainer

Usage

## S3 method for class 'qshap_tree_explainer'
print(x, ...)

Arguments

x

A qshap_tree_explainer object

...

Additional arguments (currently unused)

Value

The input x is returned invisibly. Called primarily for its side effect of printing a summary of the qshap_tree_explainer object to the console.


Print method for simple_tree

Description

Print method for simple_tree

Usage

## S3 method for class 'simple_tree'
print(x, ...)

Arguments

x

A simple_tree object

...

Additional arguments (currently unused)

Value

The input x is returned invisibly. Called primarily for its side effect of printing a summary of the simple_tree object to the console.


Print a Q-SHAP result summary

Description

Print a Q-SHAP result summary

Usage

## S3 method for class 'summary.qshap_result'
print(x, n = 10L, digits = 6L, ...)

Arguments

x

A summary.qshap_result object.

n

Non-negative integer number of top features to display (default: 10). This changes display only; the summary retains every feature.

digits

Integer number of significant digits to display, from 1 to 22.

...

Additional arguments passed to the feature table's print method.

Value

The summary object x, invisibly.


Print a Q-SHAP explainer summary

Description

Print a Q-SHAP explainer summary

Usage

## S3 method for class 'summary.qshap_tree_explainer'
print(x, digits = 6L, ...)

Arguments

x

A summary.qshap_tree_explainer object.

digits

Integer number of significant digits to display, from 1 to 22.

...

Additional arguments (currently unused).

Value

The summary object x, invisibly.


Print method for tree_summary

Description

Print method for tree_summary

Usage

## S3 method for class 'tree_summary'
print(x, ...)

Arguments

x

A tree_summary object

...

Additional arguments (currently unused)

Value

The input x is returned invisibly. Called primarily for its side effect of printing a summary of the tree_summary object to the console.


Alias for rsq

Description

This is a convenience alias for rsq() that provides a shorter function name for calculating feature-specific R-squared values.

Usage

qshap(
  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)

Value

A qshap_result object; see rsq for details.

See Also

rsq

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)


S3 Class Constructors and Methods for qshap

Description

This file contains formal S3 class definitions, constructors, validators, and methods for the qshap package objects.


Calculate Q-SHAP Loss Contributions

Description

Computes the feature-specific loss contributions using Q-SHAP decomposition. This is an internal function typically called by rsq().

Usage

qshap_loss(explainer, x, y, y_mean_ori = NULL)

Arguments

explainer

A qshap_tree_explainer object created by gazer()

x

Feature matrix or data frame

y

Response vector

y_mean_ori

Optional pre-computed mean of y (for efficiency)

Value

A matrix of loss contributions with dimensions (n_samples, n_features)


User-friendly constructor for qshap_result

Description

User-friendly constructor for qshap_result

Usage

qshap_result(
  rsq,
  feature_names = NULL,
  total_rsq = NULL,
  n_samples = NULL,
  n_features = NULL,
  loss = NULL,
  local_rsq = NULL
)

Arguments

rsq

Numeric vector of feature-specific R-squared values

feature_names

Character vector of feature names (optional)

total_rsq

Numeric total R-squared (sum of feature-specific values)

n_samples

Integer number of samples used

n_features

Integer number of features

loss

Optional raw observation-level squared-loss contribution matrix (n_samples x n_features).

local_rsq

Optional matrix of observation-level contributions to the global R-squared decomposition (n_samples x n_features). Its column sums equal the feature-specific values in rsq.

Value

A validated qshap_result object


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

An unclassed list 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)


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. Results have the single class qshap_result, which supplies print, summary, data-frame, plotting, and local-contribution methods. Use local_rsq() to extract labeled observation-level contributions when local = TRUE.

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:

Value

A qshap_result object containing:

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)


User-friendly constructor for simple_tree

Description

User-friendly constructor for simple_tree

Usage

simple_tree(
  children_left,
  children_right,
  feature,
  threshold,
  max_depth,
  n_node_samples,
  value,
  node_count,
  default_left = NULL,
  xgboost_split = FALSE
)

Arguments

children_left

Integer vector of left child indices (-1 for leaf nodes)

children_right

Integer vector of right child indices (-1 for leaf nodes)

feature

Integer vector of feature indices used for splitting (-1 for leaf nodes)

threshold

Numeric vector of threshold values for splits

max_depth

Integer maximum depth of the tree

n_node_samples

Numeric vector of node covers or weights, such as sample counts or summed Hessians

value

Numeric vector of node values

node_count

Integer total number of nodes in the tree

default_left

Logical vector indicating the missing-value direction.

xgboost_split

Logical; use XGBoost float32 strict-less routing.

Value

A validated simple_tree object


Summary method for qshap_result

Description

Computes a separate summary without printing. Use its features table or rsq_distribution vector for further analysis, and print() to control display precision and the number of displayed features.

Usage

## S3 method for class 'qshap_result'
summary(object, ...)

Arguments

object

A qshap_result object

...

Additional arguments (currently unused)

Value

A list of class summary.qshap_result, containing total_rsq, n_samples, n_features, a complete features data frame (columns feature and rsq, sorted in decreasing contribution order), rsq_distribution (min, q1, median, mean, q3, max), n_missing, threshold (0.01), n_above_threshold, loss_dim, and local_rsq_dim. Missing contributions are excluded from distribution statistics and threshold counts. Empty or entirely missing contributions yield missing distribution statistics. Numerical values are not rounded. Local matrices themselves are not copied into the summary. The threshold count is descriptive, not a significance test.

Examples

result <- qshap_result(c(0.30, 0.15, -0.05),
                       feature_names = c("a", "b", "c"), n_samples = 20)
s <- summary(result)
s$total_rsq
s$features
s$rsq_distribution
print(s, n = 2, digits = 4)

Summary method for qshap_tree_explainer

Description

Computes a separate, programmatically accessible model summary. Printing is handled by print.summary.qshap_tree_explainer().

Usage

## S3 method for class 'qshap_tree_explainer'
summary(object, ...)

Arguments

object

A qshap_tree_explainer object

...

Additional arguments (currently unused)

Value

A list of class summary.qshap_tree_explainer, containing model_type, n_trees, max_depth, base_score, node_counts for all trees, node_count_summary (minimum, mean and maximum), precomputed_initialized, and precomputed_dimensions (dimensions of v_invc and z). The original model and cached numerical arrays are not included. Summary values retain their numerical precision; an empty ensemble has missing node-count summary statistics.


User-friendly constructor for tree_summary

Description

User-friendly constructor for tree_summary

Usage

tree_summary(
  children_left,
  children_right,
  feature,
  feature_uniq,
  threshold,
  max_depth,
  sample_weight,
  init_prediction,
  node_count,
  default_left = NULL,
  xgboost_split = FALSE
)

Arguments

children_left

Integer vector of left child indices

children_right

Integer vector of right child indices

feature

Integer vector of feature indices

feature_uniq

Integer vector of unique feature indices used in tree

threshold

Numeric vector of threshold values

max_depth

Integer maximum depth

sample_weight

Numeric vector of sample weights per node

init_prediction

Numeric vector of initial predictions per node

node_count

Integer total number of nodes

default_left

Logical vector indicating the missing-value direction.

xgboost_split

Logical; use XGBoost float32 strict-less routing.

Value

A validated tree_summary object


Validator for qshap_result

Description

Validator for qshap_result

Usage

validate_qshap_result(x)

Arguments

x

A qshap_result object

Value

The validated object (invisibly) or stops with an error


Validator for qshap_tree_explainer

Description

Validator for qshap_tree_explainer

Usage

validate_qshap_tree_explainer(x)

Arguments

x

A qshap_tree_explainer object

Value

The validated object (invisibly) or stops with an error


Validator for simple_tree class

Description

Validator for simple_tree class

Usage

validate_simple_tree(x)

Arguments

x

A simple_tree object

Value

The validated object (invisibly) or stops with an error


Validator for tree_summary class

Description

Validator for tree_summary class

Usage

validate_tree_summary(x)

Arguments

x

A tree_summary object

Value

The validated object (invisibly) or stops with an error


Visualization Module for Q-SHAP Results

Description

An environment containing visualization functions for Q-SHAP results. Access functions using vis$rsq(), vis$elbow(), etc.

Usage

vis

Format

An environment with visualization functions:

rsq

Bar plot of feature-specific R-squared values

elbow

Elbow plot showing top contributing features

cumu

Cumulative explained variance plot

gcorr

Generalized correlation plot (square root of R-squared)

hist

Histogram of feature-specific R-squared contributions

density

Density plot of feature-specific R-squared contributions

loss

Interactive loss explorer (requires shiny)

loss_heatmap

Heatmap of observation-level contributions

mirror server hosted at Truenetwork, Russian Federation.