Merge pull request #124 from ModelOriented/readme-examples

More natural examples in readme

NEWS.md

@@ -2,11 +2,15 @@
 
 ## Performance improvements
 
-- Significant speed-up for data objects with *single class "data.frame"*, i.e., no data.tables or tibbles or grouped data etc. This change makes it almost as fast to work with data.frames as with matrices.
-- Slight speed-up for single-output predictions.
-- Slight speed-up for factor-valued predictions.
+- Significant speed-up for pure data.frames, i.e., no data.tables or tibbles.
+- Some small performance improvements, e.g., for factor predictions and univariate predictions.
 - Slight speed-up of `permshap()` by caching calculations for the two special permutations of all 0 and all 1. Consequently, the `m_exact` component in the output is reduced by 2.
 
+## Documentation
+
+- Rewrote many examples in the README.
+- Added reference to Erik Strumbelj and Ivan Kononeko (2014).
+
 # kernelshap 0.4.0
 
 ## Major changes

R/permshap.R

@@ -1,7 +1,7 @@
 #' Permutation SHAP
 #'
-#' Exact permutation SHAP values with respect to a background dataset.
-#' The function is currently limited to maximum 14 features.
+#' Exact permutation SHAP algorithm with respect to a background dataset,
+#' see Strumbelj and Kononenko. The function works for up to 14 features.
 #'
 #' @inheritParams kernelshap
 #' @returns
@@ -16,6 +16,9 @@
 #'     (currently `TRUE`).
 #'   - `txt`: Summary text.
 #'   - `predictions`: \eqn{(n \times K)} matrix with predictions of `X`.
+#' @references
+#'   1. Erik Strumbelj and Igor Kononenko. Explaining prediction models and individual 
+#'     predictions with feature contributions. Knowledge and Information Systems 41, 2014.
 #' @export
 #' @examples
 #' # MODEL ONE: Linear regression