modelstudio v3.1.1

- closes #112
- add new tests
- add IEMA citation
- update readme and description

Author: hbaniecki

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: modelStudio
 Title: Interactive Studio for Explanatory Model Analysis
-Version: 3.1.0.9000
+Version: 3.1.1
 Authors@R:
     c(person("Hubert", "Baniecki", role = c("aut", "cre"),
              email = "[email protected]",
@@ -15,9 +15,9 @@ Description: Automate the explanatory analysis of machine learning predictive
     models and frameworks. The main function computes various (instance and 
     model-level) explanations and produces a customisable dashboard, which 
     consists of multiple panels for plots with their short descriptions. It is 
-    possible to easily save the dashboard and share it with others. Tools for 
-    Explanatory Model Analysis unite with tools for Exploratory Data Analysis 
-    to give a broad overview of the model behavior.
+    possible to easily save the dashboard and share it with others. modelStudio 
+    facilitiates the process of Interactive Explanatory Model Analysis introduced 
+    in Baniecki et al. (2023) <10.1007/s10618-023-00924-w>.
 Depends: R (>= 3.6)
 License: GPL-3
 Encoding: UTF-8

NEWS.md

@@ -1,5 +1,6 @@
-# modelStudio (development)
-* ...
+# modelStudio 3.1.1
+* added new parameter to `modelStudio()`: `open_plots = c("fi")`, which is a vector listing plots to be initially opened (and on which positions) [(#112)](https://github.com/ModelOriented/modelStudio/issues/112)
+* fixed future warning with `DALEX::loss_default()` since `DALEX >=2.5.0`
 
 # modelStudio 3.1.0
 * changed y-axis variable labels in `SV` to the same as in `BD`

R/modelStudio.R

@@ -42,6 +42,7 @@
 #' @param B Number of permutation rounds used for calculation of SV. Default is \code{10}.
 #'  See \href{https://modelstudio.drwhy.ai/articles/ms-perks-features.html#more-calculations-means-more-time}{\bold{vignette}}
 #' @param B_fi Number of permutation rounds used for calculation of FI. Default is \code{B}.
+#' @param open_plots A vector listing plots to be initially opened (and on which positions). Default is \code{c("fi")}.
 #' @param eda Compute EDA plots and Residuals vs Feature plot, which adds the data to the dashboard. Default is \code{TRUE}.
 #' @param show_info Verbose a progress on the console. Default is \code{TRUE}.
 #' @param verbose An alias for \code{show_info}. If provided, it will override the value.
@@ -186,6 +187,7 @@ modelStudio.explainer <- function(explainer,
                                   B = 10,
                                   B_fi = B,
                                   eda = TRUE,
+                                  open_plots = c("fi"),
                                   show_info = TRUE,
                                   parallel = FALSE,
                                   options = ms_options(),
@@ -213,6 +215,14 @@ modelStudio.explainer <- function(explainer,
   if (is.null(max_features_fi)) max_features_fi <- max_features
   if (!is.null(verbose)) show_info <- verbose
   if (is.null(N)) stop("`N` argument must be an integer")
+  if (length(open_plots) > prod(facet_dim)) 
+    stop(paste0("`open_plots` is of length larger than defined by `facet_dim` dimensions.",
+                "Increase `facet_dim` or shorten `open_plots`."))
+  available_plots <- c('bd', 'sv', 'cp', 'fi', 'pd', 'ad', 'rv', 'fd', 'tv', 'at')
+  if (!all(open_plots %in% c(available_plots, toupper(available_plots))))
+    stop(paste0("`open_plots` must be a vector with the following values: 'bd',",
+                " 'sv', 'cp', 'fi', 'pd', 'ad', 'rv', 'fd', 'tv', 'at'."))
+  open_plots <- toupper(open_plots)
   #if (identical(N_fi, numeric(0))) N_fi <- NULL
 
   if (is.null(new_observation)) {
@@ -250,7 +260,11 @@ modelStudio.explainer <- function(explainer,
       loss_function <- DALEX::loss_root_mean_square
     }
   } else {
-    loss_function <- DALEX::loss_default(explainer$model_info$type)
+    if (package_version(packageVersion("DALEX")) < package_version("2.5.0")) {
+      loss_function <- DALEX::loss_default(explainer$model_info$type)  
+    } else {
+      loss_function <- DALEX::get_loss_default(explainer$model_info$type)
+    }
   }
 
   variable_splits_type <- ifelse('variable_splits_type' %in% kwargs_names,
@@ -504,6 +518,7 @@ modelStudio.explainer <- function(explainer,
                     version_text = version_text,
                     measure_text = measure_text,
                     drop_down_data = jsonlite::toJSON(drop_down_data),
+                    open_plots = as.list(open_plots),
                     eda = eda,
                     widget_id = widget_id,
                     is_target_binary = is_binary(y)

README.md

@@ -14,7 +14,7 @@
 
 The `modelStudio` package **automates the explanatory analysis of machine learning predictive models**. It generates advanced interactive model explanations in the form of a **serverless HTML site** with only one line of code. This tool is model-agnostic, therefore compatible with most of the black-box predictive models and frameworks (e.g. `mlr/mlr3`, `xgboost`, `caret`, `h2o`, `parsnip`, `tidymodels`, `scikit-learn`, `lightgbm`, `keras/tensorflow`).
 
-The main `modelStudio()` function computes various (instance and model-level) explanations and produces a **customisable dashboard**, which consists of multiple panels for plots with their short descriptions. It is possible to easily **save** the dashboard and **share** it with others. Tools for [Explanatory Model Analysis](https://ema.drwhy.ai/) unite with tools for Exploratory Data Analysis to give a broad overview of the model behavior.
+The main `modelStudio()` function computes various (instance and model-level) explanations and produces a **customisable dashboard**, which consists of multiple panels for plots with their short descriptions. It is possible to easily **save** the dashboard and **share** it with others. Tools for [Explanatory Model Analysis](https://ema.drwhy.ai) unite with tools for Exploratory Data Analysis to give a broad overview of the model behavior.
 
 <p align="center"><b>
 <a href="https://rai-covid.drwhy.ai">explain COVID-19<a> &emsp;
@@ -316,28 +316,39 @@ or with [`r2d3::save_d3_html()`](https://rstudio.github.io/r2d3/articles/publish
   <img src="man/figures/controls.png">
 </p>
 
-## Citation
+## Citations
 
 If you use `modelStudio`, please cite our [JOSS article](https://joss.theoj.org/papers/10.21105/joss.01798):
 
 ```
-@article{modelStudio,
-  author = {Hubert Baniecki and Przemyslaw Biecek},
-  title = {{modelStudio: Interactive Studio with Explanations for ML Predictive Models}},
-  year = {2019},
+@article{baniecki2019modelstudio,
+  title   = {{modelStudio: Interactive Studio with Explanations for ML Predictive Models}},
+  author  = {Hubert Baniecki and Przemyslaw Biecek},
   journal = {Journal of Open Source Software},
-  volume = {4},
-  number = {43},
-  pages = {1798},
-  url = {https://doi.org/10.21105/joss.01798}
+  year    = {2019},
+  volume  = {4},
+  number  = {43},
+  pages   = {1798},
+  url     = {https://doi.org/10.21105/joss.01798}
 }
 ```
 
-## More resources
+For a description of the Interactive EMA process, refer to our [DMKD article](https://doi.org/10.1007/s10618-023-00924-w):
+
+```
+@article{baniecki2023grammar,
+  title   = {The grammar of interactive explanatory model analysis},
+  author  = {Hubert Baniecki and Dariusz Parzych and Przemyslaw Biecek},
+  journal = {Data Mining and Knowledge Discovery},
+  year    = {2023},
+  pages   = {1--37},
+  url     = {https://doi.org/10.1007/s10618-023-00924-w}
+}
+```
 
-  - A preprint: [The Grammar of Interactive Explanatory Model Analysis](https://arxiv.org/abs/2005.00497v4)
+## More resources
 
-  - Theoretical introduction to the plots: [Explanatory Model Analysis: Explore, Explain, and Examine Predictive Models](https://ema.drwhy.ai/)
+  - Theoretical introduction to the plots: [Explanatory Model Analysis: Explore, Explain, and Examine Predictive Models](https://ema.drwhy.ai)
 
   - Vignettes: [perks and features](https://modelstudio.drwhy.ai/articles/ms-perks-features.html), [R & Python examples](https://modelstudio.drwhy.ai/articles/ms-r-python-examples.html), [modelStudio in R Markdown HTML](https://modelstudio.drwhy.ai/articles/ms-rmarkdown.html)   
 
@@ -348,4 +359,4 @@ If you use `modelStudio`, please cite our [JOSS article](https://joss.theoj.org/
 
 ## Acknowledgments
 
-Work on this package was financially supported by the `NCN Opus grant 2016/21/B/ST6/02176` and `NCBR grant POIR.01.01.01-00-0328/17`.
+Work on this package was financially supported by the National Science Centre (Poland) grant `2016/21/B/ST6/02176` and National Centre for Research and Development grant `POIR.01.01.01-00-0328/17`.

inst/d3js/modelStudio.js

@@ -26,6 +26,7 @@ var TIME = options.time,
     versionText = options.version_text,
     measureText = options.measure_text,
     dropDownData = options.drop_down_data,
+    openPlots= options.open_plots,
     EDA = options.eda,
     WIDGET_ID = options.widget_id,
     IS_TARGET_BINARY = options.is_target_binary,
@@ -502,14 +503,15 @@ function initializeStudio() {
                IS_BUTTON_CLICKED = false;
              });
   }
-
-  if (facetData.length >= 1) {
-    svg.selectAll('.enterChoiceButton').filter('#enterChoiceButton0').dispatch('click');
-    svg.select("#chosePlotButton0").select("#FI").dispatch('click');
+  
+  for (let i = 0; i < openPlots.length; i++) {
+    if (facetData.length > i) {
+      svg.selectAll(".enterChoiceButton").filter("#enterChoiceButton"+i).dispatch('click');
+      svg.select("#chosePlotButton"+i).select("#"+openPlots[i]).dispatch('click');
+    }
   }
-
-  if (facetData.length >= 2) {
-    svg.selectAll('.enterChoiceButton').filter('#enterChoiceButton1').dispatch('click');
+  if (facetData.length > openPlots.length) {
+    svg.selectAll(".enterChoiceButton").filter("#enterChoiceButton"+openPlots.length).dispatch('click');
   }
 }
 

man/modelStudio.Rd

@@ -0,0 +1,55 @@
+context("Test v3.1.1")
+
+set.seed(1313)
+v <- FALSE
+
+model <- glm(survived ~., data = DALEX::titanic_imputed, family = "binomial")
+
+explainer <- DALEX::explain(model,
+                            data = DALEX::titanic_imputed,
+                            y = DALEX::titanic_imputed$survived,
+                            verbose = v)
+
+testthat::test_that("max_features_fi, **_axis_title", {
+  ms <- testthat::expect_silent(
+    modelStudio::modelStudio(explainer,
+                             B = 2,
+                             max_features_fi = 2, 
+                             max_features = 2,
+                             options = ms_options(cp_axis_title = "pred",
+                                                  bd_axis_title = "attribution"),
+                             verbose = v)
+  )
+  testthat::expect_is(ms, "r2d3")
+})
+
+testthat::test_that("open_plots", {
+  ms <- testthat::expect_silent(
+    modelStudio::modelStudio(explainer,
+                             B = 2,
+                             open_plots = c("fi", "bd", "rv"),
+                             verbose = v)
+  )
+  testthat::expect_is(ms, "r2d3")
+  
+  testthat::expect_error(
+    modelStudio::modelStudio(explainer, 
+                             B = 2,
+                             open_plots = c("bd", "test"), 
+                             verbose = v)
+  )
+  testthat::expect_error(
+    modelStudio::modelStudio(explainer, 
+                             B = 2,
+                             facet_dim = c(2, 1),
+                             open_plots = c("pd", "ad", "cp"), 
+                             verbose = v)
+  )
+  testthat::expect_silent(
+    modelStudio::modelStudio(explainer, 
+                             B = 2,
+                             facet_dim = c(2, 1),
+                             open_plots = c("SV", "FI"), 
+                             verbose = v)
+  )
+})