Merge pull request #71 from mayer79/docu_fixes

Documentation fixes

NEWS.md

@@ -8,6 +8,7 @@ This release mainly changes the *output*. The numeric results are unchanged.
 - "hstats_matrix" object: All statistics functions, e.g., `h2_pairwise()` or `perm_importance()`, now return a "hstats_matrix". The values are stored in `$M` and can be plotted via `plot()`.
 - `perm_importance()`: The `perms` argument has been changed to `m_rep`.
 - `print()` and `summary()` methods have been revised.
+- The arguments `w` (case weights) and `y` (response) can now also be passed as column *names*.
 
 ## Minor changes
 
@@ -18,8 +19,6 @@ This release mainly changes the *output*. The numeric results are unchanged.
 - `summary.hstats()` now returns an object of class "hstats_summary" instead of "summary_hstats".
 - `average_loss()` is more flexible regarding the group `BY` argument. It can also be a variable *name*. Non-discrete `BY` variables are now automatically binned. Like `partial_dep()`, binning is controlled by the `by_size = 4` argument.
 - `average_loss()` also returns a "hstats_matrix" object with `print()` and `plot()` method. The values can be extracted via `$M`.
-- Case weights `w` can now also be passed as column name of `X` (to any function).
-- `perm_importance()` and `average_loss()`: The response(s) `y` can now also be passed as column name(s) of `X`.
 - The default `v` of `hstats()` and `perm_importance()` is now `NULL`. Internally, it is set to `colnames(X)` (minus the column names of `w` and `y` if passed as name).
 
 # hstats 0.3.0

R/average_loss.R

@@ -124,7 +124,7 @@ average_loss.ranger <- function(object, X, y,
 
 #' @describeIn average_loss Method for "mlr3" models.
 #' @export
-average_loss.Learner <- function(object, v, X, y, 
+average_loss.Learner <- function(object, X, y, 
                                  pred_fun = NULL,
                                  loss = "squared_error", 
                                  BY = NULL, by_size = 4L, 

R/hstats.R

@@ -45,7 +45,8 @@
 #' @param eps Threshold below which numerator values are set to 0. Default is 1e-10.
 #' @param verbose Should a progress bar be shown? The default is `TRUE`.
 #' @param ... Additional arguments passed to `pred_fun(object, X, ...)`, 
-#'   for instance `type = "response"` in a [glm()] model.
+#'   for instance `type = "response"` in a [glm()] model, or `reshape = TRUE` in a 
+#'   multiclass XGBoost model.
 #' @returns 
 #'   An object of class "hstats" containing these elements:
 #'   - `X`: Input `X` (sampled to `n_max` rows).

R/ice.R

@@ -4,6 +4,7 @@
 #' up to two grouping variables via `BY`.
 #'
 #' @inheritParams partial_dep
+#' @param v One or more column names over which you want to calculate the ICE.
 #' @param BY Optional grouping vector/matrix/data.frame (up to two columns), 
 #'   or up to two column names. Unlike with [partial_dep()], these variables are not
 #'   binned. The first variable is visualized on the color scale, while the second
@@ -208,7 +209,7 @@ ice.explainer <- function(object, v = v, X = object[["data"]],
 #' Print method for object of class "ice".
 #'
 #' @param x An object of class "ice".
-#' @param n Number of rows of partial dependencies to show.
+#' @param n Number of rows to print.
 #' @param ... Further arguments passed from other methods.
 #' @returns Invisibly, the input is returned.
 #' @export

R/partial_dep.R

@@ -31,6 +31,8 @@
 #' 
 #' @inheritParams hstats
 #' @inheritParams multivariate_grid
+#' @param v One or more column names over which you want to calculate the partial
+#'   dependence.
 #' @param grid Evaluation grid. A vector (if `length(v) == 1L`), or a matrix/data.frame 
 #'   otherwise. If `NULL`, calculated via [multivariate_grid()].
 #' @param BY Optional grouping vector or column name. The partial dependence
@@ -260,7 +262,7 @@ partial_dep.explainer <- function(object, v, X = object[["data"]],
 #' Print method for object of class "partial_dep".
 #'
 #' @param x An object of class "partial_dep".
-#' @param n Number of rows of partial dependencies to show.
+#' @param n Number of rows to print.
 #' @param ... Further arguments passed from other methods.
 #' @returns Invisibly, the input is returned.
 #' @export

R/perm_importance.R

@@ -1,7 +1,8 @@
 #' Permutation Importance
 #' 
 #' Calculates permutation importance for a set of features or a set of feature groups. 
-#' By default, importance is calculated for all columns in `X`.
+#' By default, importance is calculated for all columns in `X` (except column names
+#' used as response `y` or case weight `w`).
 #' 
 #' The permutation importance of a feature is defined as the increase in the average
 #' loss when shuffling the corresponding feature values before calculating predictions.
@@ -18,7 +19,7 @@
 #' @param agg_cols Should multivariate losses be summed up? Default is `FALSE`.
 #' @param normalize Should importance statistics be divided by average loss?
 #'   Default is `FALSE`. If `TRUE`, an importance of 1 means that the average loss
-#'   has doubled by shuffling that feature's column.
+#'   has been doubled by shuffling that feature's column.
 #' @inheritParams hstats
 #' @inheritParams average_loss
 #' @inherit h2_overall return