qshap: Fast Shapley Decomposition of R2 for Gradient-Boosted Trees

Gradient-boosted decision trees (GBDTs) are powerful tools for predictive modeling, but interpreting their global behavior—specifically how individual features contribute to overall model performance—remains difficult. While local explanation methods like TreeSHAP exist, they are designed for individual predictions rather than decomposing global metrics like R-squared. This paper addresses the need for a direct, efficient, and exact decomposition of R-squared for GBDT models.

The authors introduce qshap, a framework that leverages Shapley values to allocate the total R-squared of a fitted GBDT model among its input features. The method decomposes the quadratic loss of individual observations into a linear combination of standard SHAP terms and a quadratic SHAP term. By exploiting the internal structure of decision trees, the authors provide a polynomial-time algorithm that avoids the computational overhead of Monte Carlo sampling or model refitting. Furthermore, they develop a specialized, highly efficient backend for oblivious trees (used in models like CatBoost) that exploits symmetric tree structures to group observations by leaf, reducing computational complexity.

The qshap framework enables exact, global feature-specific R-squared decomposition for GBDTs. The software is implemented in both R and Python with efficient C++ backends, supporting popular libraries such as XGBoost, LightGBM, and CatBoost. The authors demonstrate that their oblivious tree implementation scales exceptionally well, with runtime showing only a weak dependence on the number of samples, making it suitable for large-scale datasets. The tool also provides rich visualization capabilities, such as elbow plots and cumulative contribution charts, to help researchers identify the most influential features in their models.

Understanding global feature importance is critical in fields like finance and biomedical science, where researchers must justify model performance and feature selection. By providing a deterministic, fast, and exact way to decompose R-squared, qshap bridges the gap between local interpretability and global model assessment, allowing for more rigorous and transparent model evaluation without the need for computationally expensive approximation methods.