More CRAN prep (#430)

* GHA test on oldrel-1 (R4.3) and oldre-2 (R4.2).

Think oldrel-1 should be OK, but oldrel-2 will fail to the change in how errors are reported in R/snapshot. Must check if they can be bypassed.

* rhub GHA setup

Created by rhub::rhub_setup()

* doc

* update news

* skip vaeac test if torch is not properly installed

* skip model input error tests on R before 4.3

* add proper references to explain

* fix links from initial winbuilder notes

* href

* references and links

* last references

* add citation

* rename vignettes

* update pkgdown site names (+aym-caus)

* remove uncessary exported functions from func list

.Rbuildignore

@@ -23,11 +23,11 @@ inst/compare_lundberg\.xgb\.obj
 ^.Rprofile
 ^python$
 ^rebuild_long_running_vignette\.R$
-^vignettes/understanding_shapr\.Rmd\.orig$
-^vignettes/understanding_shapr_vaeac\.Rmd\.orig$
-^vignettes/understanding_shapr_regression\.Rmd\.orig$
-^vignettes/understanding_shapr_asymmetric_causal\.Rmd\.orig$
-^vignettes/figure_main/*$
+^vignettes/general_usage\.Rmd\.orig$
+^vignettes/vaeac\.Rmd\.orig$
+^vignettes/regression\.Rmd\.orig$
+^vignettes/asymmetric_causal\.Rmd\.orig$
+^vignettes/figure_general_usage/*$
 ^vignettes/cache_main/*$
 ^vignettes/figure_vaeac/*$
 ^vignettes/cache_vaeac/*$

.gitignore

@@ -25,6 +25,7 @@ docs
 .idea
 .DS_Store
 
-vignettes/cache_main/
+vignettes/cache_general_usage/
 vignettes/cache_vaeac/
 vignettes/cache_regression/
+vignettes/cache_asymmetric_causal/

NAMESPACE

@@ -2,6 +2,7 @@
 
 S3method(get_model_specs,Arima)
 S3method(get_model_specs,ar)
+S3method(get_model_specs,default)
 S3method(get_model_specs,forecast_ARIMA)
 S3method(get_model_specs,gam)
 S3method(get_model_specs,glm)

NEWS.md

@@ -1,7 +1,8 @@
 # shapr 1.0.1 
 
-* Rename vaeac plotting functions [#427](https://github.com/NorskRegnesentral/shapr/pull/427))
-* Move explain() arguments `paired_shap_sampling` and `kernelSHAP_reweighting` into `extra_computation_args` [#427](https://github.com/NorskRegnesentral/shapr/pull/427))
+* Add extra_computation_args and output_args to explain_forecast() [#428](https://github.com/NorskRegnesentral/shapr/pull/428))
+* Rename vaeac plotting functions [#428](https://github.com/NorskRegnesentral/shapr/pull/428))
+* Move explain() arguments `paired_shap_sampling` and `kernelSHAP_reweighting` into `extra_computation_args` [#428](https://github.com/NorskRegnesentral/shapr/pull/428))
 * Improved and unified the documentation [#427](https://github.com/NorskRegnesentral/shapr/pull/427))
 * Remove seed argument from the boostrap function as its better handled by the mother function [#427](https://github.com/NorskRegnesentral/shapr/pull/427))
 * Renamed various internal functions to be consistent with names in the rest of the package [#427](https://github.com/NorskRegnesentral/shapr/pull/427))
@@ -52,7 +53,7 @@ This allows models with large number of features to be explained with a signific
 Uses a different set of input argument which is more appropriate for these models. 
 * Re-implementation of `approach = 'independence'` method providing significantly faster computation (no longer as a special case of the `empirical` method). 
 Also allow the method to be used on models with categorical data  ([#315](https://github.com/NorskRegnesentral/shapr/pull/315)).
-* Added 'beeswarm' and 'waterfall' plots + new coloring scheme for all plots. See the [vignette](https://norskregnesentral.github.io/shapr/articles/understanding_shapr.html#ex) for examples.
+* Added 'beeswarm' and 'waterfall' plots + new coloring scheme for all plots. See the [vignette](https://norskregnesentral.github.io/shapr/articles/general_usage.html#ex) for examples.
 * Added timing of the various parts of the explanation process. 
 
 ### Under the hood
@@ -74,7 +75,7 @@ Previously, this was not possible with the prediction functions defined internal
 
 ### Documentation improvements
 
-* The [vignette](https://norskregnesentral.github.io/shapr/articles/understanding_shapr.html) has been updated to reflect the new framework for explaining predictions, and all the new package features/functionality.
+* The [vignette](https://norskregnesentral.github.io/shapr/articles/general_usage.html) has been updated to reflect the new framework for explaining predictions, and all the new package features/functionality.
 * New vignettes also for the regression paradigm, vaeac and the asymmetric/causal Shapley values
 
 # shapr 0.2.3 (GitHub only)

R/approach.R

@@ -2,6 +2,8 @@
 #'
 #' The different choices of `approach` take different (optional) parameters,
 #' which are forwarded from [explain()].
+#' See the \href{https://norskregnesentral.github.io/shapr/articles/general_usage.html}{general usage}
+#' for more information about the different approaches.
 #'
 #' @param ... Arguments passed to specific classes. See below
 #'

R/approach_empirical.R

@@ -13,7 +13,10 @@
 #' Represents the minimum proportion of the total empirical weight that data samples should use.
 #' If e.g. `eta = .8` we will choose the `K` samples with the largest weight so that the sum of the weights
 #' accounts for 80\% of the total weight.
-#' `eta` is the \eqn{\eta} parameter in equation (15) of Aas et al (2021).
+#' `eta` is the \eqn{\eta} parameter in equation (15) of
+# nolint start
+#' \href{https://www.sciencedirect.com/science/article/pii/S0004370221000539/pdfft?md5=c3e4b95131ed944dc23b05a6170dbaee&pid=1-s2.0-S0004370221000539-main.pdf}{Aas et al. (2021)}.
+# nolint end
 #'
 #' @param empirical.fixed_sigma Positive numeric scalar.
 #' The default value is 0.1.
@@ -43,6 +46,12 @@
 #' @inheritParams default_doc_internal
 #'
 #' @export
+# nolint start
+#' @references
+#'   - \href{https://www.sciencedirect.com/science/article/pii/S0004370221000539/pdfft?md5=c3e4b95131ed944dc23b05a6170dbaee&pid=1-s2.0-S0004370221000539-main.pdf}{
+#'   Aas, K., Jullum, M., & Løland, A. (2021). Explaining individual predictions when features are dependent:
+#'   More accurate approximations to Shapley values. Artificial Intelligence, 298, 103502}
+# nolint end
 setup_approach.empirical <- function(internal,
                                      empirical.type = "fixed_sigma",
                                      empirical.eta = 0.95,

R/approach_gaussian.R

@@ -123,6 +123,7 @@ prepare_data.gaussian <- function(internal, index_features, ...) {
 #' @param min_eigen_value Numeric
 #' Specifies the smallest allowed eigen value before the covariance matrix of `x_train` is assumed to not be
 #' positive definite, and [Matrix::nearPD()] is used to find the nearest one.
+#' @keywords internal
 get_cov_mat <- function(x_train, min_eigen_value = 1e-06) {
   cov_mat <- stats::cov(x_train)
   eigen_values <- eigen(cov_mat)$values
@@ -135,6 +136,7 @@ get_cov_mat <- function(x_train, min_eigen_value = 1e-06) {
 #' get_mu_vec
 #'
 #' @inheritParams explain
+#' @keywords internal
 get_mu_vec <- function(x_train) {
   unname(colMeans(x_train))
 }

R/approach_vaeac.R

@@ -370,6 +370,11 @@ prepare_data.vaeac <- function(internal, index_features = NULL, ...) {
 #' @return A list containing the training/validation errors and paths to where the vaeac models are saved on the disk.
 #' @export
 #' @author Lars Henry Berge Olsen
+#' @references
+#'   - \href{https://www.jmlr.org/papers/volume23/21-1413/21-1413.pdf}{
+#'   Olsen, L. H., Glad, I. K., Jullum, M., & Aas, K. (2022). Using Shapley values and variational autoencoders to
+#'   explain predictive models with dependent mixed features. Journal of machine learning research, 23(213), 1-51}
+#' @keywords internal
 vaeac_train_model <- function(x_train,
                               model_description,
                               folder_to_save_model,
@@ -836,6 +841,7 @@ vaeac_train_model_auxiliary <- function(vaeac_model,
 #'
 #' @return A list containing the training/validation errors and paths to where the vaeac models are saved on the disk.
 #' @export
+#' @inherit vaeac_train_model references
 #' @author Lars Henry Berge Olsen
 vaeac_train_model_continue <- function(explanation,
                                        epochs_new,
@@ -1728,6 +1734,7 @@ vaeac_check_parameters <- function(x_train,
 #'
 #' @export
 #' @author Lars Henry Berge Olsen
+#' @inherit vaeac_train_model references
 vaeac_get_extra_para_default <- function(vaeac.model_description = make.names(Sys.time()),
                                          vaeac.folder_to_save_model = tempdir(),
                                          vaeac.pretrained_vaeac_model = NULL,
@@ -2033,6 +2040,7 @@ vaeac_get_x_explain_extended <- function(x_explain, S, index_features) {
 #' each vaeac model.
 #' @export
 #' @author Lars Henry Berge Olsen
+#' @keywords internal
 vaeac_get_evaluation_criteria <- function(explanation_list) {
   # Check if user only provided a single explanation and did not put it in a list
   if ("shapr" %in% class(explanation_list)) explanation_list <- list(explanation_list)
@@ -2074,6 +2082,7 @@ vaeac_get_evaluation_criteria <- function(explanation_list) {
 #' #' There are conducted no checks to validate the indices.
 #'
 #' @return List of objects needed to train the `vaeac` model
+#' @keywords internal
 vaeac_get_data_objects <- function(x_train,
                                    log_exp_cont_feat,
                                    val_ratio,
@@ -2600,6 +2609,7 @@ Last epoch:             %d. \tVLB = %.3f \tIWAE = %.3f \tIWAE_running = %.3f\n",
 #'
 #' @author Lars Henry Berge Olsen
 #' @export
+#' @inherit vaeac_train_model references
 plot_vaeac_eval_crit <- function(explanation_list,
                                  plot_from_nth_epoch = 1,
                                  plot_every_nth_epoch = 1,
@@ -2734,6 +2744,7 @@ plot_vaeac_eval_crit <- function(explanation_list,
 #' @return A [GGally::ggpairs()] figure.
 #' @export
 #' @author Lars Henry Berge Olsen
+#' @inherit vaeac_train_model references
 #'
 #' @examples
 #' \dontrun{