add ms_update_options

DESCRIPTION

@@ -22,8 +22,8 @@ Encoding: UTF-8
 LazyData: true
 RoxygenNote: 7.1.0
 Imports:
-    iBreakDown (>= 1.0),
-    ingredients (>= 1.0),
+    iBreakDown (>= 1.1.0),
+    ingredients (>= 1.0.0),
     r2d3,
     jsonlite,
     progress,

NAMESPACE

@@ -5,6 +5,8 @@ S3method(modelStudio,explainer)
 S3method(modelStudio,python.builtin.object)
 export(modelStudio)
 export(modelStudioOptions)
+export(ms_options)
+export(ms_update_options)
 import(progress)
 importFrom(grDevices,nclass.Sturges)
 importFrom(stats,IQR)

NEWS.md

@@ -1,8 +1,11 @@
 # modelStudio (development)
+* rename `modelStudioOptions()` to `ms_options()`
+* add new `ms_update_options()` function that updates the options of a `modelStudio` object
 * lower `B` default value from `15` to `10` and `N` default value from `400` to `300`
 * `feature_importance` is now calculated on `10*N` sampled rows from the data
 * use `ranger` instead of `randomForest` everywhere
 * remove unnecessary imports, update the documentation
+* add new class `"modelStudio"` to the `modelStudio()` output
 
 # modelStudio 1.0.2
 * fix `FD` plot on matrix-like data 

R/modelStudio.R

@@ -28,14 +28,14 @@
 #' @param parallel Speed up the computation using \code{parallelMap::parallelMap()}.
 #'  See \href{https://modeloriented.github.io/modelStudio/articles/ms-perks-features.html#parallel-computation}{\bold{vignette}}.
 #'  This might interfere with showing progress using \code{show_info}.
-#' @param options Customize \code{modelStudio}. See \code{\link{modelStudioOptions}} and
+#' @param options Customize \code{modelStudio}. See \code{\link{ms_options}} and
 #'  \href{https://modeloriented.github.io/modelStudio/articles/ms-perks-features.html#plot-options}{\bold{vignette}}.
 #' @param viewer Default is \code{external} to display in an external RStudio window.
 #'  Use \code{browser} to display in an external browser or
 #'  \code{internal} to use the RStudio internal viewer pane for output.
 #' @param ... Other parameters.
 #'
-#' @return An object of the \code{r2d3} class.
+#' @return An object of the \code{r2d3, htmlwidget, modelStudio} class.
 #'
 #' @importFrom utils head tail packageVersion
 #' @importFrom stats aggregate predict quantile IQR
@@ -157,7 +157,7 @@ modelStudio.explainer <- function(explainer,
                                   eda = TRUE,
                                   show_info = TRUE,
                                   parallel = FALSE,
-                                  options = modelStudioOptions(),
+                                  options = ms_options(),
                                   viewer = "external",
                                   ...) {
 
@@ -396,6 +396,8 @@ modelStudio.explainer <- function(explainer,
   model_studio$x$script <- remove_file_paths(model_studio$x$script, "js")
   model_studio$x$style <- remove_file_paths(model_studio$x$style, "css")
 
+  class(model_studio) <- c(class(model_studio), "modelStudio")
+
   model_studio
 }
 

R/modelStudioOptions.R → R/ms_options.R

@@ -6,10 +6,11 @@
 #' parameter in the main function. \strong{WARNING: Editing default options may cause
 #' unintended behavior.}
 #'
-#' @param ... Options to change, \code{option_name = value}.
+#' @param ... Options to change in the form \code{option_name = value}.
 #'
 #' @return \code{list} of options for \code{modelStudio}.
 #'
+#' @section Options:
 #' \subsection{Main options:}{
 #' \describe{
 #' \item{scale_plot}{\code{TRUE} Makes every plot the same height, ignores \code{bar_width}.}
@@ -66,17 +67,16 @@
 #' model_apartments <- glm(m2.price ~. , data = apartments)
 #'
 #' # create an explainer for the model
-#' explainer_apartments <- DALEX::explain(model_apartments,
-#'                                        data = apartments,
-#'                                        y = apartments$m2.price,
-#'                                        label = "glm")
+#' explainer_apartments <- explain(model_apartments,
+#'                                 data = apartments,
+#'                                 y = apartments$m2.price)
 #'
 #' # pick observations
 #' new_observation <- apartments[1:2,]
 #' rownames(new_observation) <- c("ap1","ap2")
 #'
 #' # modify default options
-#' new_options <- modelStudioOptions(
+#' new_options <- ms_options(
 #'   show_subtitle = TRUE,
 #'   bd_subtitle = "Hello World",
 #'   line_size = 5,
@@ -94,8 +94,8 @@
 #'             N = 200,  B = 5) # faster example
 #'
 #' @export
-#' @rdname modelStudioOptions
-modelStudioOptions <- function(...) {
+#' @rdname ms_options
+ms_options <- function(...) {
 
   # prepare default options
   default_options <- list(
@@ -182,3 +182,12 @@ modelStudioOptions <- function(...) {
 
   default_options
 }
+
+#' deprecated since v1.1
+#' @export
+#' @rdname ms_options
+modelStudioOptions <- function(...) {
+  warning("The 'modelStudioOptions()' function is deprecated; please use 'ms_options()' instead.")
+  ret <- ms_options(...)
+  ret
+}

R/ms_update_new_observation.R

@@ -0,0 +1 @@
+ms_update_new_observation <- NULL

R/ms_update_options.R

@@ -0,0 +1,90 @@
+#' @title Update the options of a modelStudio object
+#'
+#' @description
+#' This function updates the options of a \code{\link{modelStudio}} object.
+#' \strong{WARNING: Editing default options may cause unintended behavior.}
+#'
+#' @param object A \code{modelStudio} created with \code{modelStudio()}.
+#' @param ... Options to change in the form \code{option_name = value},
+#'  e.g. \code{time = 0}, \code{facet_dim = c(1,2)}.
+#'
+#' @return An object of the \code{r2d3, htmlwidget, modelStudio} class.
+#'
+#' @inheritSection ms_options Options
+#'
+#' @references
+#'
+#' \itemize{
+#'   \item The input object is implemented in \href{https://modeloriented.github.io/DALEX/}{\bold{DALEX}}
+#'   \item Feature Importance, Ceteris Paribus, Partial Dependence and Accumulated Dependence plots
+#' are implemented in \href{https://modeloriented.github.io/ingredients/}{\bold{ingredients}}
+#'   \item Break Down and Shapley Values plots are implemented in \href{https://modeloriented.github.io/iBreakDown/}{\bold{iBreakDown}}
+#' }
+#'
+#' @seealso
+#' Vignettes: \href{https://modeloriented.github.io/modelStudio/articles/ms-r-python-examples.html}{\bold{modelStudio - R & Python examples}}
+#' and \href{https://modeloriented.github.io/modelStudio/articles/ms-perks-features.html}{\bold{modelStudio - perks and features}}
+#'
+#' @examples
+#' library("DALEX")
+#' library("modelStudio")
+#'
+#' # fit a model
+#' model_apartments <- glm(m2.price ~. , data = apartments)
+#'
+#' # create an explainer for the model
+#' explainer_apartments <- explain(model_apartments,
+#'                                 data = apartments,
+#'                                 y = apartments$m2.price)
+#'
+#' # make a studio for the model
+#' ms <- modelStudio(explainer_apartments)
+#' ms
+#'
+#' new_ms <- ms_update_options(ms, time = 0, facet_dim = c(1,2), margin_left = 100)
+#' new_ms
+#'
+#' @export
+#' @rdname ms_update_options
+ms_update_options <- function(object, ...) {
+
+  stopifnot("modelStudio" %in% class(object))
+
+  # extract old options
+  old_options <- object$x$options
+  # input user options
+  old_options[names(list(...))] <- list(...)
+
+  new_options <- old_options
+
+  options("r2d3.shadow" = FALSE) # set this option to avoid using shadow-root
+
+  model_studio <- r2d3::r2d3(
+    data = object$x$data,
+    script = system.file("d3js/modelStudio.js", package = "modelStudio"),
+    dependencies = list(
+      system.file("d3js/hackHead.js", package = "modelStudio"),
+      system.file("d3js/myTools.js", package = "modelStudio"),
+      system.file("d3js/d3-tip.js", package = "modelStudio"),
+      system.file("d3js/d3-simple-slider.min.js", package = "modelStudio"),
+      system.file("d3js/d3-interpolate-path.min.js", package = "modelStudio"),
+      system.file("d3js/generatePlots.js", package = "modelStudio"),
+      system.file("d3js/generateTooltipHtml.js", package = "modelStudio")
+    ),
+    css = system.file("d3js/modelStudio.css", package = "modelStudio"),
+    options = new_options,
+    d3_version = "4",
+    viewer = NULL,
+    sizing = object$sizingPolicy,
+    elementId = object$elementId,
+    width = new_options$facet_dim[2]*(new_options$w + new_options$margin_left + new_options$margin_right),
+    height = 100 + new_options$facet_dim[1]*(new_options$h + new_options$margin_top + new_options$margin_bottom)
+  )
+
+  model_studio$x$script <- remove_file_paths(model_studio$x$script, "js")
+  model_studio$x$style <- remove_file_paths(model_studio$x$style, "css")
+
+  class(model_studio) <- c(class(model_studio), "modelStudio")
+
+  model_studio
+}

README.md

@@ -146,7 +146,7 @@ rownames(new_observation) <- c("id1", "id2")
 # make a studio for the model
 modelStudio(explainer,
             new_observation,
-            options = modelStudioOptions(margin_left = 140))
+            options = ms_options(margin_left = 140))
 ```
 
 ### scikit-learn [dashboard](https://modeloriented.github.io/modelStudio/scikitlearn.html)
@@ -205,7 +205,7 @@ explainer <- py_load_object("explainer_scikitlearn.pickle", pickle = "pickle")
 # make a studio for the model
 library(modelStudio)
 modelStudio(explainer, B = 5,
-            options = modelStudioOptions(margin_left = 160))
+            options = ms_options(margin_left = 160))
 ```
 
 ## Save & Share

inst/WORDLIST

@@ -33,3 +33,6 @@ keras
 lightGBM
 customizable
 customisable
+BD
+FI
+SV